---

name: add-effect description: This skill should be used when the user asks to "add a new effect", "create a transform effect", "implement a visual effect", "add a post-process shader", or when planning effect implementation. Provides the complete checklist of files to modify and commonly-missed steps.

Adding a Transform Effect

Follow this checklist when adding a new transform effect to AudioJones. Each section lists required modifications with file paths relative to repository root.

Checklist Overview

Transform effects require changes to 11 locations across 8 files. Three steps are commonly missed:

1. TransformOrderConfig::order array - Effect won't appear in reorder UI
2. GetTransformCategory() case - Effect shows "???" badge in pipeline list
3. param_registry.cpp entries - Modulatable parameters won't respond to LFOs/audio

Phase 1: Config Header

Create src/config/{effect_name}_config.h:

Copy#ifndef {EFFECT_NAME}_CONFIG_H
#define {EFFECT_NAME}_CONFIG_H

struct {EffectName}Config {
    bool enabled = false;
    // Add effect-specific parameters with defaults
};

#endif

Use snake_case for filename, PascalCase for struct name.

Phase 2: Effect Registration

Modify src/config/effect_config.h:

1. Add include at top with other config headers:

   Copy#include "{effect_name}_config.h"
   

2. Add enum entry in TransformEffectType before TRANSFORM_EFFECT_COUNT:

   CopyTRANSFORM_{EFFECT_NAME},
   

3. Add name case in TransformEffectName():

   Copycase TRANSFORM_{EFFECT_NAME}: return "Effect Name";
   

4. Add to order array in TransformOrderConfig::order initialization:

   CopyTRANSFORM_{EFFECT_NAME}
   

   Place at end of array, before closing brace. COMMONLY MISSED.

5. Add config member to EffectConfig struct:

   Copy{EffectName}Config {effectName};
   

6. Add enabled case in IsTransformEnabled():

   Copycase TRANSFORM_{EFFECT_NAME}: return e->{effectName}.enabled;
   

Phase 3: Shader

Create shaders/{effect_name}.fs:

Copy#version 330

in vec2 fragTexCoord;
out vec4 finalColor;

uniform sampler2D texture0;
uniform vec2 resolution;
// Add effect-specific uniforms

void main() {
    vec2 uv = fragTexCoord;
    vec4 color = texture(texture0, uv);

    // Effect algorithm here

    finalColor = color;
}

Phase 4: PostEffect Integration

Modify src/render/post_effect.h:

1. Add shader member in PostEffect struct:

   CopyShader {effectName}Shader;
   

2. Add uniform location members:

   Copyint {effectName}ResolutionLoc;
   int {effectName}{ParamName}Loc;
   // One int per uniform
   

Modify src/render/post_effect.cpp:

1. Load shader in LoadPostEffectShaders():

   Copype->{effectName}Shader = LoadShader(0, "shaders/{effect_name}.fs");
   

2. Add to success check (same function):

   Copy&& pe->{effectName}Shader.id != 0
   

3. Get uniform locations in GetShaderUniformLocations():

   Copype->{effectName}ResolutionLoc = GetShaderLocation(pe->{effectName}Shader, "resolution");
   pe->{effectName}{ParamName}Loc = GetShaderLocation(pe->{effectName}Shader, "{paramName}");
   

4. Add to resolution uniforms in SetResolutionUniforms() if shader uses resolution:

   CopySetShaderValue(pe->{effectName}Shader, pe->{effectName}ResolutionLoc, res, SHADER_UNIFORM_VEC2);
   

5. Unload shader in PostEffectUninit():

   CopyUnloadShader(pe->{effectName}Shader);
   

Phase 5: Shader Setup

Modify src/render/shader_setup.h:

1. Declare setup function:

   Copyvoid Setup{EffectName}(PostEffect* pe);
   

Modify src/render/shader_setup.cpp:

1. Add dispatch case in GetTransformEffect():

   Copycase TRANSFORM_{EFFECT_NAME}:
       return { &pe->{effectName}Shader, Setup{EffectName}, &pe->effects.{effectName}.enabled };
   

2. Implement setup function:

   Copyvoid Setup{EffectName}(PostEffect* pe) {
       const {EffectName}Config* cfg = &pe->effects.{effectName};
       SetShaderValue(pe->{effectName}Shader, pe->{effectName}{ParamName}Loc,
                      &cfg->{paramName}, SHADER_UNIFORM_FLOAT);
   }
   

Phase 6: UI Panel

Modify src/ui/imgui_effects.cpp:

1. Add category mapping in GetTransformCategory() switch statement. Match the category to whichever Draw*Category() function contains your UI controls. COMMONLY MISSED.

Modify src/ui/imgui_effects_{category}.cpp:

1. Add section state at file top with other static bools:

   Copystatic bool section{EffectName} = false;
   

2. Add helper function before the appropriate Draw*Category():

   Copystatic void Draw{Category}{EffectName}(EffectConfig* e, const ModSources* modSources, const ImU32 categoryGlow)
   {
       if (DrawSectionBegin("Effect Name", categoryGlow, &section{EffectName})) {
           const bool wasEnabled = e->{effectName}.enabled;
           ImGui::Checkbox("Enabled##{id}", &e->{effectName}.enabled);
           if (!wasEnabled && e->{effectName}.enabled) { MoveTransformToEnd(&e->transformOrder, TRANSFORM_{EFFECT_NAME}); }
           if (e->{effectName}.enabled) {
               ModulatableSlider("Param", &e->{effectName}.param, "effectName.param", "%.2f", modSources);
           }
           DrawSectionEnd();
       }
   }
   

3. Add helper call in the orchestrator with spacing:

   CopyImGui::Spacing();
   Draw{Category}{EffectName}(e, modSources, categoryGlow);
   

   Use ModulatableSlider for parameters that should respond to modulation. Use ModulatableSliderAngleDeg for angular parameters (displays degrees, stores radians).

Phase 7: Preset Serialization

Modify src/config/preset.cpp:

1. Add JSON macro with other config macros:

   CopyNLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT({EffectName}Config, enabled, {param1}, {param2})
   

2. Add to_json entry in to_json(json& j, const EffectConfig& e):

   Copyif (e.{effectName}.enabled) { j["{effectName}"] = e.{effectName}; }
   

3. Add from_json entry in from_json(const json& j, EffectConfig& e):

   Copye.{effectName} = j.value("{effectName}", e.{effectName});
   

Phase 8: Parameter Registration (if modulatable)

Modify src/automation/param_registry.cpp:

1. Add to PARAM_TABLE:

   Copy{"{effectName}.{param}", {{min}f, {max}f}},
   

2. Add to targets array (search for float* targets[]):

   Copy&effects->{effectName}.{param},
   

Entries in PARAM_TABLE and targets array must be at matching indices. COMMONLY MISSED.

For angular parameters, use the constants from ui_units.h:

• ROTATION_SPEED_MAX for speed fields (radians/second)
• ROTATION_OFFSET_MAX for angle/twist fields (radians)

Verification

After implementation, verify:

• Effect appears in transform order pipeline
• Effect shows correct category badge (not "???")
• Effect can be reordered via drag-drop
• Enabling effect adds it to the pipeline list
• UI controls modify effect in real-time
• Preset save/load preserves settings
• Modulation routes to registered parameters (if applicable)
• Build succeeds with no warnings

File Summary