From 934579def5bd1c4f4b0f2ef7a9d81e21de796495 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Tue, 10 Feb 2026 18:09:41 +0100
Subject: docs: Fix EFFECT keyword syntax and add automation-friendly workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fix EFFECT keyword format across all documentation and scripts - priority
modifier (+/=/–) is required but was missing from examples.

**Documentation fixes:**
- doc/HOWTO.md: Added missing + to EFFECT example
- doc/RECIPE.md: Added priority modifiers to examples
- tools/shadertoy/README.md: Fixed test path, clarified workflow
- tools/shadertoy/convert_shadertoy.py: Updated output instructions

**New automation guide:**
- doc/EFFECT_WORKFLOW.md: Complete step-by-step checklist for AI agents
  - Exact file paths and line numbers
  - Common issues and fixes
  - Asset ID naming conventions
  - CMakeLists.txt dual-section requirement
  - Test list instructions (post_process_effects vs scene_effects)

**Integration:**
- CLAUDE.md: Added EFFECT_WORKFLOW.md to Tier 2 (always loaded)
- doc/AI_RULES.md: Added "Adding Visual Effects" quick reference
- README.md: Added EFFECT_WORKFLOW.md to documentation list

**CMakeLists.txt:**
- Disabled incomplete cube_sphere_effect.cc (ShaderToy conversion WIP)

**Timeline:**
- Commented out incomplete CubeSphereEffect
- Removed obsolete constructor argument

Fixes #issue-with-effect-syntax

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 tools/shadertoy/README.md            | 22 ++++++++++++++++------
 tools/shadertoy/convert_shadertoy.py | 16 ++++++++++------
 2 files changed, 26 insertions(+), 12 deletions(-)

(limited to 'tools/shadertoy')

diff --git a/tools/shadertoy/README.md b/tools/shadertoy/README.md
index e734684..d12865f 100644
--- a/tools/shadertoy/README.md
+++ b/tools/shadertoy/README.md
@@ -2,6 +2,8 @@
 
 Quick guide to convert ShaderToy shaders to demo effects.
 
+**For complete workflow:** See `doc/EFFECT_WORKFLOW.md` for full integration checklist.
+
 ## Quick Start (Automated)
 
 ```bash
@@ -95,16 +97,24 @@ In `src/gpu/demo_effects.h`:
 In `workspaces/main/timeline.seq`:
 ```
 SEQUENCE 0.0 0
-  EFFECT MyEffectEffect 0.0 10.0 0
+  EFFECT + MyEffectEffect 0.0 10.0
+```
+
+### 7. Update CMakeLists.txt
+
+Add effect source to `CMakeLists.txt` GPU_SOURCES (both headless and normal mode sections):
+```cmake
+src/gpu/effects/myeffect_effect.cc
 ```
 
-### 7. Update Tests
+### 8. Update Tests
 
-In `tests/test_demo_effects.cc`:
-- Add `"MyEffectEffect"` to test list
-- Increment `EXPECTED_*_COUNT`
+In `src/tests/gpu/test_demo_effects.cc`:
+- Add to `post_process_effects` list (lines 80-93) if it's a post-process effect
+- OR add to `scene_effects` list (lines 125-137) if it's a scene effect
+- Example: `{"MyEffectEffect", std::make_shared<MyEffectEffect>(fixture.ctx())},`
 
-### 8. Build & Test
+### 9. Build & Test
 
 ```bash
 cmake --build build -j4
diff --git a/tools/shadertoy/convert_shadertoy.py b/tools/shadertoy/convert_shadertoy.py
index 4956cfd..29eca1d 100755
--- a/tools/shadertoy/convert_shadertoy.py
+++ b/tools/shadertoy/convert_shadertoy.py
@@ -383,7 +383,7 @@ def main():
 
     print("✓ Files generated")
     print()
-    print("Next steps:")
+    print("Next steps (see doc/EFFECT_WORKFLOW.md for details):")
     print()
     print("1. Add shader to workspaces/main/assets.txt:")
     print(f"   shaders/{snake_name}.wgsl")
@@ -392,13 +392,17 @@ def main():
     print(f'   #include "gpu/effects/{snake_name}_effect.h"')
     print()
     print("3. Add to timeline in workspaces/main/timeline.seq:")
-    print(f"   EFFECT {effect_name}Effect 0.0 10.0 0")
+    print(f"   EFFECT + {effect_name}Effect 0.0 10.0")
     print()
-    print("4. Update tests/test_demo_effects.cc:")
-    print(f'   - Add "{effect_name}Effect" to test list')
-    print("   - Increment EXPECTED_*_COUNT")
+    print("4. Add to CMakeLists.txt GPU_SOURCES (both headless and normal mode):")
+    print(f"   src/gpu/effects/{snake_name}_effect.cc")
     print()
-    print("5. Build and test:")
+    print("5. Update src/tests/gpu/test_demo_effects.cc:")
+    print(f'   - Add "{{{effect_name}Effect", std::make_shared<{effect_name}Effect>(fixture.ctx())}}" to appropriate list')
+    print("   - Use post_process_effects (lines 80-93) for post-process effects")
+    print("   - Use scene_effects (lines 125-137) for scene effects")
+    print()
+    print("6. Build and test:")
     print("   cmake --build build -j4")
     print("   ./build/demo64k")
     print()
-- 
cgit v1.2.3