Introduction

Math · not · meshes v0.4.0 — GregOrigin

Instant Organic Caves (IOC) is a high-performance C++ plugin for Unreal Engine that replaces static cave asset packs with a fully deterministic, parametric procedural pipeline. It generates tunnels and density-field caverns asynchronously on background threads, with explicit production budgets, seam-safe open-world chunk streaming, runtime mesh carving, Biome Volume spatial overrides, Blueprint gameplay APIs, and full multiplayer replication.

Quickstart & Demo

Compatibility

Dedicated Tools Menu

Everything lives under Tools > Instant Organic Caves. The wizard also has a shortcut on Window > IOC Setup Wizard…, for parity with the other editor tools that open a window.

Quick start

Demos

The Setup Wizard

Open it from Tools > Instant Organic Caves, from Window, or with IOC.OpenSetupWizard. It is native C++ Slate and depends on no Python, Blueprint, or Editor Utility Widget.

The wizard is a five-step pass. Each step both configures the cave and checks the project can actually build it:

Undo Added Actors in the footer removes everything the run placed, in one click, so the wizard is safe to experiment with. Settings persist between sessions, and Save / Load Profile carries a configuration between projects.

Automated Showcase & Flythrough

The Cinematic Showcase is controlled by the AIOCShowcaseLauncher actor. It handles async readiness guards, streaming, PCG scattering, and baked mesh transitions automatically.

ShowcaseLauncher CallInEditor Buttons

• Start Showcase — run with diagnostic HUD and generation metrics.
• Start Capture Showcase — immersive captions only, no debug text (ideal for video).
• Start Interactive Demo — builds the walkable interactive tour instead of the flythrough (the same as ticking Interactive Demo, bInteractiveMode). The tour spawns at the launcher's location.
• Clear Showcase — destroys all generated actors, restores viewport camera.

AIOCProceduralActor

The core placement unit. Drop one into a level, configure its categories in the Details panel, and click Generate Cave. Every property tagged ReplicatedUsing=OnRep_GenerationSettings synchronises across network sessions.

Cave Presets — IOC category

Shape Properties — IOC|Shape

Noise & Octave Controls — IOC|Shape

Perlin Tunnels — IOC|Tunnel

Enable bGenerateTunnel to switch from blob/cavern mode to tunnel mode. The algorithm computes the distance field to a line segment between two points, then adds 3D Perlin Noise to the radius, producing a guaranteed connected organic tube.

Spline-Driven Tunnels — IOC|Tunnel

Enable bUseSpline (requires bGenerateTunnel) to drive the tunnel axis using the built-in USplineComponent (CaveSpline). Edit spline points directly in the viewport for full art-direction.

Appearance — IOC|Appearance

LOD System — IOC|Advanced

A dedicated second UDynamicMeshComponent (LODMeshComponent) is generated at a coarser voxel resolution. The system switches to this mesh when the camera exceeds LODDistance.

Production Budgets — IOC|Production

These caps protect runtime memory and frame time. Generation is aborted and an error logged if any limit is exceeded.

Advanced Options — IOC|Advanced

Real-Time Performance Stats — IOC|Performance

Open World AIOCStreamingManager

Place one AIOCStreamingManager in your level. The server-authority tracks all player pawns, spawns replicated AIOCProceduralActor chunks within StreamRadius, and destroys chunks beyond the unload radius. Chunk creation is throttled per update tick.

All spawned chunks use world-space noise (forced) and are positioned on a voxel-aligned integer grid so neighboring chunks share identical density samples at their boundaries — eliminating seams.

The chunk grid is centred on the manager's location, and CaveStartOffset is relative to it, so place the manager where the streamed cave should be. (Before this release the manager had no root component and sat at the world origin wherever it was put.)

Streaming Parameters

Player Coupling — IOC Streaming|Coupling

When bAutoCouplePlayerAtStart is enabled, the manager teleports the first possessed pawn to its world position + CaveStartOffset, holds it at PlayerStartHoldHeight until the initial chunk finishes generating, then uses a downward trace of GroundProbeDistance to land the player on the first solid surface.

Blueprint API — Streaming Manager

void  RebuildAroundLocation(FVector WorldLocation);  // Force-recentre chunk grid
FVector GetEffectiveChunkSize() const;               // Voxel-aligned actual chunk size
int32 GetLoadedChunkCount()  const;
int32 GetPendingChunkCount() const;
// Runtime carving (authority only)
void CarveStreamedCavesAtLocation(FVector WorldLocation, float Radius);
void ClearStreamedRuntimeCarves();

Spatial Override AIOCBiomeVolume

Place AIOCBiomeVolume brush actors overlapping your generation bounds. When the actor runs generation, each voxel position is tested against all Biome Volumes and the highest-Priority override is applied, allowing local characteristic changes without separate actors.

Carving System

IOC provides two carving mechanisms: static editor-time carving via component, and dynamic runtime carving via Blueprint.

Static Editor Carving — UIOCCarvingComponent

Add a UIOCCarvingComponent as a child of any AIOCProceduralActor. The actor automatically discovers all attached carving components at generation time and guarantees the carved volume is hollow regardless of the noise field. Use for guaranteed doors, corridors, or entry points.

Runtime Carving — IOC Gameplay

Blow holes at runtime from Blueprint or C++ (server-authority only). Carve operations are stored in RuntimeCarves (a SaveGame TArray), replicated via OnRep_RuntimeCarves, and re-applied when the mesh regenerates.

// Server-side carving example
void AMyGameMode::OnExplosion(FVector WorldPos, float Radius)
{
    if (AIOCProceduralActor* Cave = FindNearestCave(WorldPos))
        Cave->CarveAtLocation(WorldPos, Radius);
}

Player Carving — AIOCCharacter, IOC|Carving

The demo character can carve where it aims. It is off by default: its carve keys live in their own mapping context, installed only while carving is on, so a project's own use of the left mouse button is untouched.

Decoration Scatter System

Add FIOCScatterLayer entries to DecorationLayers on the actor (or SharedDecorationLayers on the StreamingManager). After meshing, IOC scatters HISM instances on matching faces.

Eight props ship with the plugin in /InstantOrganicCaves/InstantOrganicCaves/Geometry/ — the segment repeats because the plugin mounts its Content folder as /InstantOrganicCaves and keeps the meshes in a folder of the same name inside it — so a furnished cave needs no sourced art: SM_IOC_Rock_A, _B and _C (boulder down to gravel), SM_IOC_Crystal_A and _B, SM_IOC_Geode, SM_IOC_Stalactite and SM_IOC_Stalagmite. Each has two LODs, simple collision, and its pivot at its base, growing along +Z. With bAlignToNormal on, scatter points that axis along the surface normal — into the cave, so down on a ceiling — which is what hangs a stalactite; instances neither float nor sink. With alignment off, props keep the world's up and a ceiling layer grows into the rock.

Material Pipeline

IOC ships a hybrid pipeline. The default MI_IOC_CaveWalls lets you toggle between a zero-texture procedural rock and high-fidelity PBR textures.

Pure Math Material — M_IOC_MathRock

Uses Absolute World Position fed into multi-octave Simplex Noise to generate base color, moss patches, roughness variation, and subtle normal perturbation — algorithmically, with zero texture bytes.

• Zero memory footprint — 0 bytes of texture data.
• Infinite scale — identical on a 1 m crawlspace or a 500 m cavern.
• Seam-free — world-space sampling makes chunks tile seamlessly.
• Smart Vertex Color support — blends color tones automatically per surface zone.

PBR Texture Mode

Set UsePBRTexture = true on MI_IOC_CaveWalls and select a CaveStyleTexture:

• T_RockObsidian — Glossy volcanic glass with organic ridges.
• T_RockLimestone — Porous light-grey stalactite surface.
• T_RockAlien — Dark bioporous stone with bioluminescent green veins.

Also included: M_IOC_SmartCave and MI_IOC_SmartCave_Inst — add slope-based height blending for additional biome variation.

Triplanar UV Generation

IOC generates UVs using Box Mapping (Triplanar) projection. Each face's dominant world normal (X, Y, or Z) selects the projection axis, eliminating stretching on steep walls and overhanging ceilings. The TextureTiling property scales UV frequency globally.

Smart Vertex Colors

When bGenerateSmartColors is enabled, the generation pass writes vertex colors based on each vertex's world-space Z normal:

• Red — floor intensity (normal.Z > 0.7)
• Green — ceiling intensity (normal.Z < −0.5)
• Blue — wall intensity (intermediate normals)

PCG Integration

The IOCVoxelCore PCG node exposes the same density field as the Actor to the Procedural Content Generation graph. Use it to scatter PCG points on the generated surface for foliage, crystals, lighting, or AI spawn points.

Included PCG Content

• IOC_Graph_Master — Master PCG graph with IOCVoxelCore pre-wired.
• IOC_Fn_OrganicNoise — Noise-based density filtering sub-graph.
• IOC_Fn_ScatterCrystals — Crystal decoration scatter layer preset.
• NewPCGGraphInstance — Ready-to-use PCG Graph Instance.

NavMesh Integration

Set bAutoRebuildNavMesh = true on the actor or the StreamingManager. After each mesh commit IOC requests a NavMesh rebuild scoped to the actor's bounds, enabling AI navigation in freshly generated geometry.

Multiplayer Networking & Replication

Authority-only functions

All mutation functions are BlueprintAuthorityOnly: CarveAtLocation, ClearRuntimeCarves, CarveStreamedCavesAtLocation.

Delegates

// Broadcast when async task begins
FIOCGenerationStartedSignature OnGenerationStarted;  // (AIOCProceduralActor*)

// Broadcast when async task completes
// bCancelled=true if superseded; bWillRegenerate=true if another request is pending
FIOCGenerationFinishedSignature OnGenerationFinished; // (Actor*, bCancelled, bWillRegenerate)

Async Generation Architecture

All generation runs on an AnyBackgroundThreadNormalTask worker. The pipeline stages are:

1. Bounds validation — abort if MaxVoxelCount exceeded.
2. Parallel voxel evaluation — ParallelFor across the X axis (multi-core, since v1.1).
3. Biome Volume sampling — POD copies of FIOCBiomeData read (no UObject access on worker thread).
4. Marching Cubes meshing via GeometryScripting.
5. Laplacian smoothing passes.
6. UV generation — triplanar box mapping.
7. Smart vertex colors (optional).
8. LOD mesh — same pipeline at VoxelSize × LODVoxelSizeMultiplier.
9. Decoration scatter — HISM placements computed on background thread.
10. Game thread commit — applies mesh, collision, material, HISM data.

An std::atomic<bool> bCancelRequested inside FIOCGenerationState allows a new request to safely cancel an in-flight task without unsafe UObject access.

Static Mesh Baking — IOC|Production|Bake

Once satisfied with a procedural cave, bake it to a permanent UStaticMesh asset. Press the Bake to Static Mesh CallInEditor button (Editor-only).

Spectacular Features

Domain Warping

Set DomainWarpIntensity > 0 to displace the noise sampling position by a secondary noise field. This creates folded, twisted, biopunk cave silhouettes. The Alien Hive preset uses a high intensity (~300). Available on both the Actor and StreamingManager.

Terrace Steps

Set TerraceSteps > 0 to quantise the density field into discrete horizontal bands. The Canyon Strata preset demonstrates this with a geological layered appearance. Also available on the StreamingManager and Biome Volumes.

Console Commands

Blueprint API Quick Reference

AIOCProceduralActor

AIOCCharacter

FInstantOrganicCavesModule (C++)

AIOCStreamingManager

Troubleshooting