path: root/doc/EFFECT_WORKFLOW.md

# Effect Creation Workflow

**Target Audience:** AI coding agents and developers

Automated checklist for adding new visual effects to the demo.

---

## Quick Reference

**For ShaderToy conversions:** Use `tools/shadertoy/convert_shadertoy.py` then follow steps 3-8 below.

**For custom effects:** Follow all steps 1-8.

---

## Step-by-Step Workflow

### 1. Create Effect Files

**Location:**
- Header: `src/gpu/effects/<effect_name>_effect.h`
- Implementation: `src/gpu/effects/<effect_name>_effect.cc`
- Shader: `workspaces/main/shaders/<effect_name>.wgsl`

**Naming Convention:**
- Class name: `<EffectName>Effect` (e.g., `TunnelEffect`, `PlasmaEffect`)
- Files: `<effect_name>_effect.*` (snake_case)

**Base Class:**
- Post-process effects: inherit from `PostProcessEffect`
- Scene effects: inherit from `Effect`

**Template:** See `tools/shadertoy/template.*` or use `convert_shadertoy.py`

### 2. Add Shader to Assets

**File:** `workspaces/main/assets.txt`

**Format:**
```
SHADER_<UPPER_SNAKE_NAME>, NONE, shaders/<effect_name>.wgsl, "Effect description"
```

**Example:**
```
SHADER_TUNNEL, NONE, shaders/tunnel.wgsl, "Tunnel effect shader"
```

**Asset ID:** Will be `AssetId::ASSET_SHADER_<UPPER_SNAKE_NAME>` in C++

### 3. Add to CMakeLists.txt

**File:** `CMakeLists.txt`

**Action:** Add `src/gpu/effects/<effect_name>_effect.cc` to **BOTH** GPU_SOURCES sections:
- Headless mode section (around line 141-167)
- Normal mode section (around line 171-197)

**Location:** After similar effects (post-process with post-process, scene with scene)

**Example:**
```cmake
# In headless section (line ~152):
        src/gpu/effects/solarize_effect.cc
        src/gpu/effects/tunnel_effect.cc        # <-- Add here
        src/gpu/effects/chroma_aberration_effect.cc

# In normal section (line ~183):
        src/gpu/effects/solarize_effect.cc
        src/gpu/effects/tunnel_effect.cc        # <-- Add here
        src/gpu/effects/chroma_aberration_effect.cc
```

### 4. Include in demo_effects.h

**File:** `src/gpu/demo_effects.h`

**Action:** Add include directive:
```cpp
#include "gpu/effects/<effect_name>_effect.h"
```

**Location:** Alphabetically with other effect includes

### 5. Add to Timeline

**File:** `workspaces/main/timeline.seq`

**Format:**
```
SEQUENCE <start_time> <priority>
  EFFECT <+|=|-> <EffectName>Effect <local_start> <local_end> [params...]
```

**Priority Modifiers (REQUIRED):**
- `+` : Increment priority
- `=` : Same priority as previous effect
- `-` : Decrement priority (for backgrounds)

**Example:**
```
SEQUENCE 0.0 0
  EFFECT + TunnelEffect 0.0 10.0
```

**Common Mistake:** Missing priority modifier (`+`, `=`, `-`) after EFFECT keyword

### 6. Update Tests

**File:** `src/tests/gpu/test_demo_effects.cc`

**Action:** Add effect to appropriate list:

**Post-Process Effects (lines 80-93):**
```cpp
{"TunnelEffect", std::make_shared<TunnelEffect>(fixture.ctx())},
```

**Scene Effects (lines 125-137):**
```cpp
{"TunnelEffect", std::make_shared<TunnelEffect>(fixture.ctx())},
```

**3D Effects:** If requires Renderer3D, add to `requires_3d` check (line 148-151)

### 7. Build and Test

```bash
# Full build
cmake --build build -j4

# Run effect tests
cmake -S . -B build -DDEMO_BUILD_TESTS=ON
cmake --build build -j4 --target test_demo_effects
cd build && ./test_demo_effects

# Run all tests
cd build && ctest
```

### 8. Verify

**Checklist:**
- [ ] Effect compiles without errors
- [ ] Effect appears in timeline
- [ ] test_demo_effects passes
- [ ] Effect renders correctly: `./build/demo64k`
- [ ] No shader compilation errors
- [ ] Follows naming conventions

---

## Common Issues

### Build Error: "no member named 'ASSET_..._SHADER'"

**Cause:** Shader not in assets.txt or wrong asset ID name

**Fix:**
1. Check `workspaces/main/assets.txt` has shader entry
2. Asset ID is `ASSET_` + uppercase entry name (e.g., `SHADER_TUNNEL` → `ASSET_SHADER_TUNNEL`)

### Build Error: "undefined symbol for architecture"

**Cause:** Effect not in CMakeLists.txt GPU_SOURCES

**Fix:** Add `.cc` file to BOTH sections (headless and normal mode)

### Timeline Parse Error: "Expected '+', '=', or '-'"

**Cause:** Missing priority modifier after EFFECT keyword

**Fix:** Use `EFFECT +`, `EFFECT =`, or `EFFECT -` (never just `EFFECT`)

### Test Failure: Effect not in test list

**Cause:** Effect not added to test_demo_effects.cc

**Fix:** Add to `post_process_effects` or `scene_effects` list

---

## Automation Script Example

```bash
#!/bin/bash
# Example automation for AI agents

EFFECT_NAME="$1"  # CamelCase (e.g., "Tunnel")
SNAKE_NAME=$(echo "$EFFECT_NAME" | sed 's/\([A-Z]\)/_\L\1/g' | sed 's/^_//')
UPPER_NAME=$(echo "$SNAKE_NAME" | tr '[:lower:]' '[:upper:]')

echo "Creating effect: $EFFECT_NAME"
echo "  Snake case: $SNAKE_NAME"
echo "  Upper case: $UPPER_NAME"

# 1. Generate files (if using ShaderToy)
# ./tools/shadertoy/convert_shadertoy.py shader.txt "$EFFECT_NAME"

# 2. Add to assets.txt
echo "SHADER_${UPPER_NAME}, NONE, shaders/${SNAKE_NAME}.wgsl, \"${EFFECT_NAME} effect\"" \
    >> workspaces/main/assets.txt

# 3. Add to CMakeLists.txt (both sections)
# Use Edit tool to add to both GPU_SOURCES sections

# 4. Add include to demo_effects.h
# Use Edit tool to add #include line

# 5. Add to timeline.seq
# Use Edit tool to add EFFECT line with priority modifier

# 6. Add to test file
# Use Edit tool to add to appropriate test list

# 7. Build
cmake --build build -j4
```

---

## See Also

- `tools/shadertoy/README.md` - ShaderToy conversion guide
- `doc/SEQUENCE.md` - Timeline format documentation
- `doc/CONTRIBUTING.md` - General contribution guidelines
- `src/gpu/effects/` - Existing effect examples