VoxelForge/Source/VoxelForge/Public/VoxelRedefinedDensityField.h

#pragma once

#include "CoreMinimal.h"
#include "VoxelTypes.h"

class UVoxelGenerator;

#if WITH_EDITOR
/**
 * Step 2d editor research field. It is intentionally separate from the gameplay evaluator and
 * is selected only by the default-off voxel.ResearchRedefinedDensityField console variable.
 *
 * The field is a connected, archetype-sized cave lattice with an authored walkable floor at each
 * passage landing. Its macro shape is evaluated directly in world space; bounded, continuous
 * hash-value noise is added at every full-resolution sample. The brick classifier is permitted to
 * skip only when a Lipschitz bound on the macro field plus the exact maximum detail amplitude
 * proves that the final sign is uniform throughout the brick and its marching-cubes halo.
 */
namespace VoxelForgeRedefinedDensityField
{
    /** Proof sample width shared by the research mesher and the region-evaluation harness. */
    constexpr int32 ParameterizedBrickSamples = 4;
    /** Uniform fill magnitude used after a 16 metre sign proof. */
    constexpr float ParameterizedUniformDensity = 16.0f * 100.0f / VOXEL_SIZE;

    /** Per-worker, per-brick state. The opaque plan pointer is valid until the layout changes. */
    struct FBrickEvaluationContext
    {
        const void* PlanToken = nullptr;
        bool bPlanResolved = false;
        bool bMayContainPassage = true;
        bool bChunkResolved = false;
        bool bIsGapChunk = false;
        bool bHasDiffMods = false;
        bool bMacroXYPrecomputed = false;
        FIntVector BrickOrigin = FIntVector::ZeroValue;
        FIntVector BrickSize = FIntVector::ZeroValue;
        FIntVector Chunk = FIntVector::ZeroValue;
        TArray<float> FloorByXY;
        TArray<float> GridAirByXY;
        TArray<float> DetailFadeByXY;
        TArray<float> LandingHorizontalByXY;
        TArray<float> LandingApproachByXY;
        TArray<float> LandingBridgeHorizontalByXY;
        TArray<float> LandingBridgeFloorByXY;
        TArray<int32> PassageCandidates;
    };

    /** Cell-level controls for the separate editor-only parameterized cave field. */
    struct FGenerationParameters
    {
        float RoomPitchVoxels = 144.0f;
        float MinimumRoomRadiusFraction = 0.30f;
        float MaximumRoomRadiusFraction = 0.45f;
        float RoomHeightVoxels = 192.0f;
        float FloorReliefVoxels = 8.0f;
        float TunnelRadiusVoxels = 28.0f;
        float TunnelHalfHeightVoxels = 26.0f;
        float LoopProbability = 0.20f;
        float VerticalShaftProbability = 0.10f;
        float ShaftRadiusVoxels = 18.0f;
        float PillarProbability = 0.10f;
        float LedgeProbability = 0.20f;
        float FloatingMassProbability = 0.10f;
        float SpireProbability = 0.25f;
        float BasinProbability = 0.0f;
        float BasinDepthVoxels = 0.0f;
        float WaterLevelFraction = 0.5f;
    };

    /** Brick-local immutable room cells used by step 2e evaluation and its final-field proof. */
    struct FParameterizedBrickContext
    {
        const void* PlanToken = nullptr;
        const void* RoomCellCacheToken = nullptr;
        bool bPlanResolved = false;
        bool bChunkResolved = false;
        bool bIsGapChunk = false;
        bool bHasDiffMods = false;
        bool bMayContainPassage = true;
        FIntVector BrickOrigin = FIntVector::ZeroValue;
        FIntVector BrickSize = FIntVector::ZeroValue;
        FIntVector Chunk = FIntVector::ZeroValue;
        FIntPoint RoomCellCacheMin = FIntPoint::ZeroValue;
        FIntPoint RoomCellCacheSize = FIntPoint::ZeroValue;
        TArray<int32> PassageCandidates;
    };

    enum class EBrickFallbackReason : uint8
    {
        None,
        UnsupportedState,
        ChunkOrStrateBoundary,
        PassageBounds,
        MixedMacroInterval
    };

    struct FBrickCounters
    {
        uint64 Tested = 0;
        uint64 Skipped = 0;
        uint64 EvaluatedSamples = 0;
    };

    VOXELFORGE_API bool IsEnabled();
    VOXELFORGE_API void SetEnabled(bool bEnabled);
    VOXELFORGE_API float GetDetailScale();
    VOXELFORGE_API void SetDetailScale(float Scale);

    /** The parameterized cave field is editor-only and default-off. -1 rolls per strate. */
    VOXELFORGE_API bool IsParameterizedEnabled();
    VOXELFORGE_API void SetParameterizedEnabled(bool bEnabled);
    /** Select the frozen step 2e implementation while the step 2f audit measures its gates. */
    VOXELFORGE_API void SetLegacyStep2eAuditMode(bool bEnabled);
    VOXELFORGE_API void SetParameterSet(int32 ParameterSet);
    VOXELFORGE_API int32 GetParameterSet();
    VOXELFORGE_API int32 GetParameterSetCount();
    VOXELFORGE_API bool GetParameterSetInfo(
        int32 ParameterSet, const TCHAR*& OutName, FGenerationParameters& OutParameters);

    /** Evaluate the separate parameterized room / tunnel network, including edits/passages. */
    VOXELFORGE_API float EvaluateParameterized(
        const UVoxelGenerator& Generator, float WorldX, float WorldY, float WorldZ,
        float* OutPreEditDensity = nullptr, float DetailScale = 1.0f);

    /** Evaluate only the parameterized room/tunnel macro, before passage overlays and seals. */
    VOXELFORGE_API float EvaluateParameterizedMacroOnly(
        const UVoxelGenerator& Generator, float WorldX, float WorldY, float WorldZ);

    /** Describe the candidate room SDF values at a point for step 2f proof diagnosis. */
    VOXELFORGE_API FString DescribeParameterizedMacroAt(
        const UVoxelGenerator& Generator, float WorldX, float WorldY, float WorldZ);

    /** Return the active parameterized detail signal for the band-limit research gate. */
    VOXELFORGE_API float EvaluateParameterizedDetail(
        const UVoxelGenerator& Generator, float WorldX, float WorldY, float WorldZ);

    VOXELFORGE_API float EvaluateParameterizedWithDetailValue(
        const UVoxelGenerator& Generator, float WorldX, float WorldY, float WorldZ,
        float DetailValue, float* OutPreEditDensity = nullptr, float DetailScale = 1.0f,
        const FParameterizedBrickContext* Context = nullptr);

    /** Evaluate a Z column while reusing its XY-dependent room graph data. */
    VOXELFORGE_API void EvaluateParameterizedColumnWithDetailValues(
        const UVoxelGenerator& Generator, float WorldX, float WorldY, float WorldZStart,
        const float* DetailValues, int32 DetailStride, int32 Count, float* OutValues,
        const FParameterizedBrickContext* Context = nullptr, float DetailScale = 1.0f,
        int32 SampleStep = 1);

    VOXELFORGE_API bool TryClassifyParameterizedBrick(
        const UVoxelGenerator& Generator, FIntVector OriginVoxels, FIntVector Size,
        bool& bOutAir, float DetailScale = 1.0f,
        bool* bOutEvaluatedMacroCentre = nullptr,
        EBrickFallbackReason* OutFallbackReason = nullptr,
        int32 SampleStep = 1);

    VOXELFORGE_API void BuildParameterizedBrickContext(
        const UVoxelGenerator& Generator, FIntVector OriginVoxels, FIntVector Size,
        FParameterizedBrickContext& OutContext, int32 SampleStep = 1);

    /** Evaluate a mixed brick with one shared room/passage setup for all Z samples. */
    VOXELFORGE_API void EvaluateParameterizedDensityBrick(
        const UVoxelGenerator& Generator, FIntVector OriginVoxels, FIntVector Size,
        float DetailScale, FParameterizedBrickContext& InOutContext,
        TArray<float>& InOutDetail, TArray<float>& InOutColumnValues,
        TArray<float>& OutValues, int32 SampleStep = 1);

    /** Evaluate the new field, including existing passage carving and player diffs. */
    VOXELFORGE_API float Evaluate(const UVoxelGenerator& Generator, float WorldX, float WorldY,
                                  float WorldZ, float* OutPreEditDensity = nullptr,
                                  float DetailScale = 1.0f);

    /** Build mathematically identical multi-scale noise for one integer-lattice brick. */
    VOXELFORGE_API void BuildDetailBrick(const UVoxelGenerator& Generator,
        FIntVector OriginVoxels, FIntVector Size, float DetailScale,
        TArray<float>& OutDetail, FBrickEvaluationContext* OutContext = nullptr,
        bool bParameterized = false, int32 SampleStep = 1);

    /** Evaluate with a detail value produced by BuildDetailBrick. */
    VOXELFORGE_API float EvaluateWithDetailValue(const UVoxelGenerator& Generator,
        float WorldX, float WorldY, float WorldZ, float DetailValue,
        float* OutPreEditDensity = nullptr, float DetailScale = 1.0f,
        const FBrickEvaluationContext* Context = nullptr);

    /** Prove a world-aligned box has one final density sign; false means evaluate every point. */
    VOXELFORGE_API bool TryClassifyBrick(
        const UVoxelGenerator& Generator, FIntVector OriginVoxels, FIntVector Size,
        bool& bOutAir, float DetailScale = 1.0f,
        bool* bOutEvaluatedMacroCentre = nullptr,
        EBrickFallbackReason* OutFallbackReason = nullptr);

    /** Reset this thread's immutable plan cache; used by deterministic editor experiments. */
    VOXELFORGE_API void ResetThreadCache();
}
#endif