# modulation module

## Related source files

This directory contains guidance; implementations remain in the parent `Source/`
directory:

- `../ModulationMatrix.h`, `../ModulationMatrix.cpp`
- `../MacroControls.h`, `../MacroControls.cpp`
- `../RAVEButton.h`, `../RAVEButton.cpp`, which define `RaveController`

## Rules

- Use `bool` return codes for bounded inserts (`addConnection`, `addAssignment`).
- Require a cap on connection and assignment counts (`kMaxConnections`, `kMaxAssignments`).
- Serialise and restore state through `juce::ValueTree` so presets survive save and load.
- Never accept a `ModTarget::None` connection; reject it and return false.
- RaveController applies a non-destructive boost to render settings. It does not write APVTS parameters or keep a restoration snapshot.
- Keep the existing RAVEButton filenames unless a rename is explicitly in scope.

## GUI/audio state

Hold `Engine::getControlLock()` while reading or editing the control-side matrix,
macro assignments, or LFO shapes. The audio thread tries that lock once per block
and copies into reserved audio-side storage. If the lock is busy, it keeps the
previous settings and continues rendering. Never iterate the control-side vectors
from the render path.

Master and FX-mix modulation use global sources directly. Per-voice sources for
those destinations come from the newest active voice.

If `addConnection` or `addAssignment` returns false, handle the failed insert.

This file refines the repository-root AGENTS.md for the related sources.