# engine module

## Related source files

This directory contains guidance; the implementation remains in `../Engine.h`
and `../Engine.cpp`. The preparation rules below are requirements for changes;
current buffer resizing and lazy wavetable issues are recorded in the root AGENT.md.

## Rules

- Own the voice pool, LFOs, wavetable library, FX rack, matrix and macros by value.
- Read every APVTS value through the null-guarding `v()` helper.
- Build the `RenderContext` once per block and pass it to voices as `const&`.
- Size `mixBuffer` once in `prepare()` and only `clear()` it per block.
- Prebuild wavetables in `prepare()` before the first render.
- Clamp the final output with the soft limiter.
- Never call `setSize` on any buffer inside `processBlock`.

## IF-THEN

- IF a per-block buffer is needed THEN allocate it in `prepare()` and clear it per block.
- IF a module needs the matrix, macros or wavetables THEN go through Engine accessors rather than reaching into another module.

## Examples

```cpp
// BAD: per-callback buffer reconfiguration on the audio thread
void processBlock (...)
{
    mixBuffer.setSize (2, n, false, false, true);
    ...
}
```

```cpp
// GOOD: size once, clear per block
void prepare (double sr, int blockSize)
{
    mixBuffer.setSize (2, blockSize, false, false, true);
}
void processBlock (...)
{
    mixBuffer.clear();
    ...
}
```

This file overrides /AGENT.md where they conflict.