BeatSyncToolkit

# Before You Start — Prerequisites BEGINNER

This documentation assumes you can navigate Unreal Editor comfortably and make basic Blueprint connections. If you’re brand new, don’t worry — you can still follow along, but these basics will help a lot.

Data Assets (quick explanation)

A Data Asset is an Unreal asset used to store structured configuration data. BeatSyncToolkit uses Data Assets for Music Profiles (playlists, BPM, stems, defaults, etc.). You edit the profile once, then every placed Conductor can reference it.

# 1. What BeatSyncToolkit Does

BeatSyncToolkit lets you drive adaptive music in Unreal Engine using gameplay-friendly Blueprint nodes. It provides beat/bar timing, state-based music selection with per-state playlists, optional stem layers, and a zone system that can override the global music state and add extra layers — all without requiring a custom GameInstance.

Key Features

• Beat/bar clock (Timer-based) with an OnBar event for quantized changes — no Quartz dependency.
• State system (E_BST_MusicState): switch music by gameplay state, optionally quantized to the next bar. New states can be added by extending the enum + defining a matching StateConfig in your profile — see Adding a New State.
• Per-state playlist: each state can contain multiple tracks; auto-advance to the next track when the current ends.
• Two-base crossfade playback (Base A / Base B) for smooth transitions between tracks and states.
• Optional stem layers (E_BST_MusicLayer: Drums, Bass, Harmony, Melody, FX). Layers are always started muted and faded in/out — no restart.
• Event-based layers: add/remove/clear layers via global Blueprint nodes (BFL_BST) with optional next-bar quantization.
• Multi-layer event calls: add any number of layers in one node (array input), with optional next-bar quantization.
• Start/Stop Music: optionally start silent and trigger BST_StartMusic / BST_StopMusic from gameplay or demo interactions.
• Zone system (BP_BST_MusicZone): priority-based TopZone selection, zone state override, extra layers, and optional per-zone profile override.
• Zone + event layer arbitration: effective layers are the OR combination of zone layers and event layers.
• Quantized zone layer updates: zone layer changes can be applied immediately or on the next bar.
• Playlist Track Lock: lock the currently playing track so it restarts instead of advancing — event-based and optional zone-based.
• Low-friction UX: all gameplay calls go through a Blueprint Function Library. No manual Conductor references required.

What You Need to Place in Your Level

// In your Combat Manager / AI Director / GameMode:
OnEnemySpawned (or OnCombatStart)
  BST_SetMusicState(WorldContextObject=Self, NewState=Combat)

// When player enters boss arena trigger:
OnBossArenaEntered
  BST_AddLayer(WorldContextObject=Self, Layer=Drums, QuantizeToNextBar=true)

// Example: keep the current intense track looping during phase 2
OnBossHealthBelow50Percent
  BST_LockCurrentTrack(WorldContextObject=Self)

OnBossDefeated
  BST_UnlockCurrentTrack(WorldContextObject=Self)

# 2. Quick Start BEGINNER

Get BeatSyncToolkit up and running in about 10 minutes.

BST_StartMusic(WorldContextObject)
BST_StopMusic(WorldContextObject)
BST_SetMusicState(WorldContextObject, NewState)
BST_AddLayer(WorldContextObject, Layer, QuantizeToNextBar)
BST_AddLayers(WorldContextObject, Layers[], QuantizeToNextBar)
BST_RemoveLayer(WorldContextObject, Layer, QuantizeToNextBar)
BST_ClearLayers(WorldContextObject, QuantizeToNextBar)
BST_LockCurrentTrack(WorldContextObject)
BST_UnlockCurrentTrack(WorldContextObject)

# 3. Included Assets & Files

# 4. Core Concepts BEGINNER

Profile  (DA_BST_MusicProfile)
  └── StateConfig  (F_BST_StateConfig)
        ├── State:  E_BST_MusicState   ← e.g. Explore, Combat
        └── Playlist:  TrackEntry[]
              └── TrackEntry  (F_BST_TrackEntry)
                    ├── BaseSound      ← main audio (required)
                    ├── BPM            ← beats per minute
                    ├── BeatsPerBar    ← time signature
                    └── Layer Stems (Drums/Bass/Harmony/Melody/FX)    ← optional stems

# 5. Creating & Editing Music Profiles

5.1 Create a Custom Profile

5.2 Fill a StateConfig (Playlist)

In each StateConfig: set the State (E_BST_MusicState), add one or more TrackEntry items to the Tracks array, and provide accurate BPM and BeatsPerBar for each track.

5.3 Fill a TrackEntry

Each TrackEntry is the complete definition for one piece of music in a playlist.

5.3.1 F_BST_LayerDef Fields (Per-Layer Configuration)

Each layer slot (Drums, Bass, Harmony, Melody, FX) inside a TrackEntry uses the F_BST_LayerDef struct. Here are all configurable fields:

5.3.2 Audio Preparation Guide

Before importing your music into Unreal, follow these guidelines to ensure BeatSyncToolkit works reliably.

Supported Audio Formats

Stem Preparation Rules

• Same BPM: All stems for one track must share the exact same BPM. The Conductor uses a single beat clock per track.
• Same length: Export all stems with identical start/end points. Pad shorter stems with silence if needed.
• Same sample rate: Use a consistent sample rate across all stems (44100 Hz or 48000 Hz recommended).
• Mono vs Stereo: Both work. Use stereo for full-mix base tracks and wide stems (pads, ambience). Mono is fine for punchy elements (kick, snare) if you want to save memory.
• No built-in fades: Do not add fade-in/fade-out to your stem files. BeatSyncToolkit handles all fading at runtime via LayerDef settings.
• Loop-ready: If you want seamless looping, make sure your audio starts and ends cleanly on a beat boundary. Avoid silence at the start or end of the file.

5.4 Assign Profile to the Conductor

Select BP_BST_Conductor in your level. Set ActiveProfile to your custom profile asset. Set AutoStartState to the initial state. Press Play.

BST_RecomputeDefaultLayersForCurrentTrack()

# 6. Gameplay API (BFL_BST)

BFL_BST is the only thing your gameplay Blueprints need to call. It finds BP_BST_Conductor in the current world and forwards the request internally.

State Requests (Priority Overrides)

State Requests are built for temporary, event-driven overrides (AI combat, boss phases, cutscenes, scripted moments) where you want the music to automatically revert when the event ends.

• Push a request when the event starts.
• Remove the same request when the event ends.
• If multiple requests are active, higher Priority wins (requests only compete with other requests).
• Tip: If you have many instances (multiple AI, repeated triggers), use scoped request keys so each instance cannot overwrite another.
• Requests override the global baseline. If any State Request is active, the winning request (highest Priority) overrides GlobalRequestedState.
• Zones win by default. If you are inside a TopZone that is forcing a state (TopZone.ZoneState is not NONE), the zone keeps control unless the winning request is pushed with ForceWhileInZone = true.
• When requests end, the system falls back automatically. After the last request is removed, the Conductor returns to the zone’s state (if still inside a forced zone), otherwise to GlobalRequestedState.
• Note: BST_SetMusicState updates GlobalRequestedState but does not cancel active requests.
• BST_ClearRequests clears every active request at once (useful for respawn, level reset, cutscene skip).

Normal Requests vs Scoped Requests

Every state request is stored under a key called RequestId. If two systems use the same key, they are editing the same request.

• Normal request → You pick a globally-unique RequestId (good for singletons like cutscenes, boss phases, scripted moments).
• Scoped request → The key is built from ScopeKey + RequestName (good when the same Blueprint can exist many times, like AI enemies or repeated triggers).

How to use scoped requests

• Recommended (if available in your build): Use the request nodes that include a Scope/ScopeKey input. Plug Self for per-actor scope, and keep your request name short (e.g., Combat).
• Fallback (works in any build): Manually build a unique RequestId by combining a scope value (like the AI actor name) with a short request name (e.g., Enemy_12_Combat). Push and remove using the exact same string.

Example A2 — Multiple AI (Scoped)

// Per AI instance (preferred):
BST_PushStateRequest(Scoped(Self, "Combat"), Danger, 20, false, true)

// When that same AI ends the situation:
BST_RemoveStateRequest(Scoped(Self, "Combat"), true)

Example A — AI Combat (Auto-Revert)

// When AI spots the player:
BST_PushStateRequest("AI_Combat", Danger, 20, false, true)

// When AI loses the player:
BST_RemoveStateRequest("AI_Combat", true)

Example B — Cutscene (Can Override Forced Zones)

// Cutscene start (override forced zones by using ForceWhileInZone=true):
BST_PushStateRequest("Cutscene", Cinematic, 100, true, true)

// Cutscene end:
BST_RemoveStateRequest("Cutscene", true)

Tip: If you have multiple temporary systems and want to “return to normal” quickly, call BST_ClearRequests instead of tracking every RequestId.

← Inside any Blueprint (Actor, Widget, GameMode, etc.)

BST_SetMusicState(
    WorldContextObject: self         ← drag "self" node here
    NewState:           Combat
)

← "self" gives the node a valid World reference.
   BST_GetConductor uses it to find BP_BST_Conductor in that world.

BST_SetMusicState(
    WorldContextObject: ← left empty / not connected
    NewState:           Combat
)

← WorldContextObject is null.
   BST_GetConductor returns Found=false.
   Nothing happens. No error, no crash — silent fail.

# 7. Conductor Settings & Variables

These are the main user-facing variables shown in the Conductor's Details panel.

Runtime Variables (FYI)

At runtime the Conductor maintains CurrentState, CurrentTrack, beat clock values (BPM / BeatsPerBar / CurrentBeat), pending requests (PendingState, pending layer ops, pending zone layers), zone tracking (ActiveZones, TopZone, ActiveZoneLayers), and track lock flags (bEventTrackLock, bZoneTrackLock, bTrackLockActive).

# 8. Zone System INTERMEDIATE

Zones are overlap-based. When the player enters or exits zones, the Conductor maintains an ActiveZones array and selects the TopZone by highest ZonePriority. Only the TopZone's settings are applied at any time.

8.1 Zone Properties

8.2 Overlapping Zones & Priority

When inside multiple zones, the Conductor picks TopZone by the highest ZonePriority. If TopZone changes, the Conductor reapplies zone override (state / profile) and zone layers. Leaving a TopZone triggers reselection of the next best zone, or disables zone override entirely if none remain.

8.3 Zone + Gameplay State Interaction

Gameplay requests via BST_SetMusicState set GlobalRequestedState. If ZoneOverrideActive is true, the TopZone's ZoneState can override what actually plays. When you leave all zones, the Conductor returns to GlobalRequestedState automatically.

# 9. Arbitration Rules ADVANCED

When gameplay, zones, and events request different things at the same time, the Conductor follows deterministic priority rules.

9.1 State Resolution Priority

The Conductor resolves the effective desired state using these deterministic rules:

1. Forced Zone State — If ZoneOverrideActive is true and TopZone.ZoneState is not NONE, the zone becomes the effective desired state by default.
2. State Requests — If there is no forced zone state, the winning request (highest Priority among requests) becomes the effective desired state.
3. GlobalRequestedState — Fallback from BST_SetMusicState.

9.2 Profile Resolution Priority

ProfileInUse is resolved together with the effective desired state (via BST_ResolveDesiredStateAndProfile_Now). Rule: Use the zone’s OverrideProfile only when the zone is the source of the desired state (TopZone.ZoneState). If the desired state comes from a State Request or from GlobalRequestedState, then ProfileInUse = ActiveProfile. This prevents “state not found” issues when a zone override profile does not contain a requested state.

9.3 Layer Resolution (OR Combination)

A layer is active if any source requests it:

# 10. Quantization (Next-Bar Changes)

Quantization applies changes exactly on the next bar boundary — keeping transitions musically clean.

10.1 State Quantization

When bQuantizeStateChangesToBar is ON, state requests wait until the next bar boundary. On BST_OnBar, the Conductor re-resolves the effective desired state/profile using the current TopZone (if any) + active State Requests + your latest GlobalRequestedState, then switches only if needed. This prevents “stale” zone states from applying if you enter/exit zones before the bar.

Effective State Quantization (Zones vs Conductor)

There are two related values:

• bQuantizeStateChangesToBar — your default preference (instance-editable on the Conductor).
• Quantize State Changes to Bar Effective — the runtime value actually used by the system. This is resolved whenever TopZone changes.

10.2 Event Layer Ops Quantization

Queued layer ops are applied on each bar in a deterministic order:

1) Clear          ← optional PendingClearEventLayers
2) Remove        ← PendingRemoveLayers[]
3) Add           ← PendingAddLayers[] (only if track has that stem)
4) ApplyNow     ← BST_ApplyEventLayersNow()

10.3 Zone Layer Set Quantization

When zone layer changes are quantized, the Conductor stores PendingZoneLayers and sets bHasPendingZoneLayerSet=true. On bar, BST_ApplyPendingZoneLayers_OnBar copies pending layers into ActiveZoneLayers, clears the flag, and calls BST_ApplyEventLayersNow.

# 11. Playlist, Auto-Advance & Track Lock

11.1 Base Playback & Crossfade

The Conductor uses two base AudioComponents (Base A and Base B). When switching tracks or states, it crossfades from the active base to the other via BST_CrossfadeBaseTo. bUsingBaseA tracks which base is active — OnAudioFinished events from the inactive base are ignored.

11.2 Auto-Advance (Play Next Track)

If bAutoAdvancePlaylist is ON, when the active base finishes, BST_PlayNextTrack_SameState fires. The next track is chosen from the current state's playlist, avoiding immediate repeats when possible. After selection: beat clock restarts, base crossfades, layer components are ensured playing muted, and active layers are re-applied.

11.3 Track Lock

Track Lock prevents auto-advance for the current track. When locked and the active base finishes, the Conductor restarts CurrentTrack instead of advancing. Event-based lock (from BFL_BST) takes priority over zone-based lock (from TopZone).

11.4 Advance Lock (Anti Double-Advance)

The Conductor briefly sets an internal Advance Lock during transitions to prevent double-advance (e.g. if both base finished events fire near a switch). This lock auto-clears after AdvanceLockSeconds.

# 12. Practical Examples

Example A — Exploration / Combat with Quantized Transitions

// Enable quantization on the Conductor
Conductor.bQuantizeStateChangesToBar = true

// If your game uses per-zone state-quantize overrides, refresh the runtime effective flag:
Conductor.BST_ResolveEffectiveStateQuantize()

// Normal gameplay:
BST_SetMusicState(Explore)

// Combat starts — change applies cleanly on next bar:
BST_SetMusicState(Combat)

// Combat ends:
BST_SetMusicState(Explore)

Example B — Layered Tension (Event Layers)

// Ensure your Combat tracks include a Drums stem
BST_AddLayer(Drums)       ← fade in drums
BST_RemoveLayer(Drums)    ← fade out drums
// No Drums stem on current track → safely ignored

Example C — Zone Overrides + Extra Layers

Place a BP_BST_MusicZone for a "Danger Area". Set ZonePriority high, ZoneState = Danger, and ExtraLayers = [FX].

Walk into the zone: state is overridden and FX layer enables. Walk out: music returns to GlobalRequestedState and FX turns off — unless it's still requested by event layers.

Example D — Overlapping Zones (TopZone Selection)

Place Zone A (Priority 10) and Zone B (Priority 20) overlapping. Inside both: Zone B is TopZone. Leave Zone B while still in Zone A: the Conductor automatically switches back to Zone A's behavior.

Example E — Track Lock during a Boss Fight

// Boss fight begins:
BST_LockCurrentTrack()      ← track restarts on finish

// Boss fight ends:
BST_UnlockCurrentTrack()    ← auto-advance resumes

# 13. Debugging & Troubleshooting

Common Setup Issues

Debug Flags

Enable these on BP_BST_Conductor to get console output:

bDebugPrint          ← state switches, track picks, bar events
bDebugZones         ← zone enter/exit, TopZone changes, overrides applied
bDebugProfiles      ← profile resolution, state config lookups

Sanity Checklist

• Exactly one Conductor exists in the level.
• ActiveProfile contains an entry for the target state.
• Each TrackEntry has BaseSound set and correct BPM / BPB.
• Your desired layer's LayerDef sound is valid for that track.
• Zones have collision enabled and overlap events firing.

# 14. Advanced Features (Optional) #ADVANCED

For power users who want to understand internal responsibilities. Most games only need the BFL nodes and profile / zone setup.

# 15. Known Limitations & Roadmap

15.1 Current Limitations

These are intentional design boundaries or features not yet implemented. None of these prevent shipping a game with BeatSyncToolkit.

15.2 Roadmap

BeatSyncToolkit is designed to be expandable. Upcoming systems are toggles, they will not break the current workflow.

# 16. Glossary / Key Terms BEGINNER

Quick definitions for common terms used in this documentation.

# 17. Frequently Asked Questions (FAQ)

Quick answers to the most common questions.

# 18. Support & Contact

Need help or want to report an issue? Reach out to us.

Email Support

For questions, bug reports, or feature requests, contact us at:

nonfigurestudio@gmail.com