Event Sound Component

The Event Sound Component (UEventSoundComponent) is a UActorComponent that listens for character reveal events from the text animator and plays corresponding sound effects. It provides per-character audio feedback for typewriter effects and supports punctuation delays to simulate natural reading rhythm.

Feature Overview

Feature	Description
Per-character sounds	Different sound effects can be played for each revealed character
Punctuation delays	Brief pauses inserted after punctuation (commas, periods, etc.)
Performance control	At most MaxSoundsPerTick sounds processed per frame (default 8, keeps overhead ≤1ms)

Core API

Sound Mapping

// Set the sound for a specific character
void SetSoundForCharacter(int32 Character, TSoftObjectPtr<USoundBase> Sound);

// Get the sound for a specific character
TSoftObjectPtr<USoundBase> GetSoundForCharacter(int32 Character) const;

// Remove sound mapping for a character
void RemoveSoundForCharacter(int32 Character);

// Clear all sound mappings
void ClearAllSounds();

Punctuation Delays

// Set extra delay for a punctuation character (seconds)
void SetPunctuationDelayForCharacter(int32 Character, float DelaySeconds);

// Get delay value for a character
float GetPunctuationDelayForCharacter(int32 Character) const;

// Reset to default configuration
void ResetPunctuationDelaysToDefault();

// Clear all delay configurations
void ClearPunctuationDelays();

Binding Management

// Auto-find and bind to a TextAnimator on the same Actor
void BindToAnimator();

// Unbind the current Animator
void UnbindFromAnimator();

// Directly set the Animator instance (alternative to auto-binding)
void SetAnimator(UTextAnimator* InAnimator);

Configuration Properties

Property	Type	Default	Description
bAutoBindToAnimator	bool	true	Auto-bind to TextAnimator on the same Actor at BeginPlay
MaxSoundsPerTick	int32	8	Maximum sounds processed per frame (controls CPU overhead)

Internal Mechanism

Sound Queue

The component maintains a FIFO sound queue (PendingSoundQueue), processed frame-by-frame in TickComponent():

1. HandleOnCharacterRevealed() adds characters to the queue
2. ProcessSoundQueue() processes up to MaxSoundsPerTick characters from the front of the queue each frame
3. The PendingSoundHead index enables efficient dequeue operations without actual element removal

Punctuation Cooldown

The PunctuationCooldownRemaining timer is set when a punctuation character is encountered. Sound processing is suspended during this period, creating a natural reading pause.

Sound Cache

CharacterSoundMap (TMap<TCHAR, TSoftObjectPtr<USoundBase>>) stores character-to-sound mappings. LoadedSoundCache (TMap<int32, TObjectPtr<USoundBase>>) caches asynchronously loaded sound objects in memory, avoiding repeated loading.

NOTE

TCHAR cannot be used as a UPROPERTY key type, so the public API uses int32 parameters while the internal mapping uses TCHAR keys.

Usage Examples

Blueprint usage:

1. Add a UEventSoundComponent to your Actor Blueprint
2. Call BindToAnimator() in BeginPlay (or rely on bAutoBindToAnimator)
3. Use SetSoundForCharacter() to configure sounds for common characters
4. Use SetPunctuationDelayForCharacter() to configure delays for punctuation

C++ usage:

// Create and configure sound component
UEventSoundComponent* SoundComp = CreateDefaultSubobject<UEventSoundComponent>(TEXT("TextSound"));
SoundComp->bAutoBindToAnimator = true;

// Set sounds for all vowel letters (simulating speech synthesis)
SoundComp->SetSoundForCharacter('a', VowelSound);
SoundComp->SetSoundForCharacter('e', VowelSound);
// ...