SweejTech Docs

SweejAmbience Technical Reference ​

This document provides technical details about SweejAmbience components, properties, and extension points.

Component Architecture ​

SweejAmbienceComponent ​

The foundation of the ambience system:

UPROPERTY(VisibleAnywhere, Transient, Category = "Sound")
float Weight{ 0.0f };

UPROPERTY(VisibleAnywhere, Transient, Category = "Sound")
float Level{ 0.0f };

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Sound")
int32 Priority{0};

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Sound")
float MaxWeight{1.0f};

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Sound")
float ScatterSpotsThreshold{1.0f};

Key properties:

  • Weight: Current contribution to the mix (0-1 range), calculated dynamically
  • Level: Final volume multiplier based on weight and priority
  • Priority: Determines precedence when volumes overlap (higher values take precedence)
  • MaxWeight: Maximum possible contribution to the mix (0-1 range)
  • ScatterSpotsThreshold: Level at which scatter spots begin playing (0-1 range)

SweejAmbienceVolume ​

Defines the spatial bounds of ambient sounds:

UPROPERTY(VisibleAnywhere, Transient, Category = "Sound")
float Proximity{0};

UPROPERTY(EditAnywhere, Category = "Sound")
float AttenuationDistance{ 100.0f };

Key properties:

  • Proximity: Current distance from listener (0-1 range, 1 = fully inside)
  • AttenuationDistance: How far from the volume edge sounds begin to fade in

SweejAmbienceSound ​

A simple actor for placing non-volumetric ambient sounds:

  • Useful for environment-wide ambience or global sounds
  • Contains a SweejAmbienceComponent for consistent control
  • Can serve as a base for custom ambient behavior

AreaType System ​

UPROPERTY(EditAnywhere, Category = "AreaType Properties")
TArray<FSweejAreaTypePresetProperty> AreaTypePresetProperties;

UPROPERTY(EditAnywhere, Category = "AreaType Properties")
TMap<FSweejAmbienceAreaTypeEnumValue, FSweejSoundWaveList> AreaTypeSoundWaves;

AreaTypes require:

  • User-defined enumeration for area classifications in Project Settings
  • Each AreaType has a numeric ID for reference in the system
  • AreaTypePresetProperties define properties across different AreaTypes
  • AreaTypeSoundWaves associate sound waves with each AreaType

The SweejAmbienceAreaTypePreset asset allows storing properties and sounds by AreaType.

AreaType Preset Assets ​

AreaType presets store property configurations and sound associations:

FSweejAreaTypePresetProperty ​

  • Defines custom properties for each AreaType (float, int, bool values)
  • Allows per-AreaType customization of audio parameters
  • Accessible through MetaSound for dynamic processing

FSweejSoundWaveList ​

  • Stores arrays of SoundWaves associated with each AreaType
  • Enables content switching based on environment
  • Supports different sound assets for indoor vs outdoor scenarios

Ambience Definitions ​

The SweejAmbienceDefinition asset stores reusable configurations:

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Sound")
FSweejAmbienceAreaTypeEnumValue AreaType;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Sound")
TObjectPtr<USoundBase> SoundAsset{nullptr};

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Sound")
TArray<TObjectPtr<USoundEffectSubmixPreset>> ReverbEffectChain;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Sound")
TArray<TObjectPtr<USweejAmbienceScatterSpot>> ScatterSpotAssets;

Scatter Spot Configuration ​

UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Scatter Spots")
TArray<FScatterSpot> ScatterSpots;

UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Scatter Spots")
bool bEnablePreWarmedSpots{ false };

Each scatter spot configuration includes:

  • Repeat Time: Controls interval between sound triggers
  • Distance: Sets random distance from listener
  • Height: Configures vertical variation
  • Pre-warming: Enables quicker initial sound triggering

Component Relationships ​

Architecture Overview ​

The Ambience system uses a hierarchical structure:

  • SweejAmbienceComponent: Core functionality for volume interaction and sound control
  • SweejAmbienceVolume: Spatial definition of ambient areas
  • SweejAmbienceSound: Non-volumetric ambient sounds
  • SweejAmbienceDefinition: Reusable configurations
  • SweejAmbienceScatterSpot: Point-source audio elements
  • Tracer Component: Automatic environment detection

Weight Calculation Process ​

  1. Each component calculates proximity to listener
  2. Proximity values determine contribution weights
  3. Priority system resolves overlaps
  4. MaxWeight caps individual contributions
  5. Crossfades between volumes based on proximity

Extension Points ​

Blueprint Integration ​

Control weights and properties via Blueprint:

  • Access component properties directly
  • Create custom ambient behaviors
  • Respond to area changes and other system events

Tracer Component ​

The tracer component provides automatic area detection:

  • Uses line traces to detect environment characteristics
  • Converts trace results to ambience parameters
  • Adjusts ambient sounds based on environment without manual volumes

Watch Demo: Tracer Component

Performance Considerations ​

Optimization Tips ​

  • Use fewer, larger volumes when possible rather than many small ones
  • Limit the number of active scatter spots per frame
  • Optimize MetaSound node usage for AreaType access
  • Consider using pre-warmed scatter spots for faster initial audio buildup
  • Monitor the number of active ambience components during runtime

Best Practices ​

  • Use AreaTypePresets for shared property configurations
  • Implement efficient trace calculations in Tracer Component
  • Avoid overly complex reverb chains that impact performance
  • Test with multiple simultaneous players to check scaling

Reverb Effect Chain ​

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Sound")
TArray<TObjectPtr<USoundEffectSubmixPreset>> ReverbEffectChain;

The reverb system works by:

  • Applying effects to a dedicated reverb submix
  • Calculating primary and secondary reverbs based on active volumes
  • Using a mix parameter to determine blend between primary and secondary effects
  • Automatically adjusting reverb based on listener position