From 873fa985bb4b3ec3841fa77adc16a99184cb9507 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Thu, 5 Feb 2026 00:15:00 +0100
Subject: feat: Replace explicit priorities with stack-based priority modifiers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Simplifies effect priority management by using relative modifiers instead
of explicit numbers, making timeline reordering much more practical.

## New Priority System

Effects now use priority modifiers after EFFECT keyword:
- `+` increment priority by 1 (or start at 0 if first)
- `=` keep same priority as previous effect
- `-` decrement priority (or start at -1 if first, for background)

Old syntax:
```
EFFECT FlashEffect 0.0 0.5 0
EFFECT FadeEffect 0.1 0.3 1
EFFECT BgCube 0.2 3 -1
```

New syntax:
```
EFFECT - BgCube 0.2 3        # Priority -1 (background)
EFFECT + FlashEffect 0.0 0.5  # Priority 0
EFFECT + FadeEffect 0.1 0.3   # Priority 1
```

## Benefits

✓ Reordering effects no longer requires renumbering all priorities
✓ Priority relationships are explicit and relative
✓ File order matches render order (easier to understand)
✓ Same-priority effects clearly marked with `=`
✓ Background layers (-1) clearly marked with `-`
✓ Reduces errors when reorganizing timelines

## Implementation

- Updated seq_compiler to parse +/=/- modifiers
- Tracks current priority per sequence
- First effect sets base priority (0 or -1)
- Subsequent effects modify relative to previous
- Generated C++ code unchanged (still uses integer priorities)

## Changes to demo.seq

- All effects updated to use new syntax
- Effects reordered by priority within sequences
- Priority gaps removed (were likely unintentional)
- Comments updated to reflect new system

## Documentation

- Updated SEQUENCE.md with new syntax
- Added examples showing +, =, - usage
- Explained priority calculation rules

This makes timeline authoring significantly more maintainable, especially
when experimenting with different effect orderings during development.
---
 tools/seq_compiler.cc | 45 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 3 deletions(-)

(limited to 'tools')

diff --git a/tools/seq_compiler.cc b/tools/seq_compiler.cc
index 45cfc1a..7ac921f 100644
--- a/tools/seq_compiler.cc
+++ b/tools/seq_compiler.cc
@@ -467,13 +467,52 @@ int main(int argc, char* argv[]) {
                   << ": EFFECT found outside of SEQUENCE\n";
         return 1;
       }
-      std::string class_name, start, end, priority;
-      if (!(ss >> class_name >> start >> end >> priority)) {
+      std::string priority_mod, class_name, start, end;
+      if (!(ss >> priority_mod >> class_name >> start >> end)) {
         std::cerr << "Error line " << line_num
-                  << ": EFFECT requires <Class> <start> <end> <priority>\n";
+                  << ": EFFECT requires <+|=|-> <Class> <start> <end>\n";
         return 1;
       }
 
+      // Validate priority modifier
+      if (priority_mod != "+" && priority_mod != "=" && priority_mod != "-") {
+        std::cerr << "Error line " << line_num
+                  << ": Priority modifier must be '+', '=', or '-', got: " << priority_mod << "\n";
+        return 1;
+      }
+
+      // Calculate priority based on modifier and sequence state
+      static int current_priority = 0;
+      static bool first_in_sequence = true;
+      static const SequenceEntry* last_seq = nullptr;
+
+      // Reset priority tracking for new sequence
+      if (current_seq != last_seq) {
+        current_priority = 0;
+        first_in_sequence = true;
+        last_seq = current_seq;
+      }
+
+      // Handle first effect in sequence
+      if (first_in_sequence) {
+        if (priority_mod == "-") {
+          current_priority = -1;  // Background layer
+        } else {
+          current_priority = 0;   // Default start (+ or =)
+        }
+        first_in_sequence = false;
+      } else {
+        // Update priority based on modifier for subsequent effects
+        if (priority_mod == "+") {
+          current_priority++;
+        } else if (priority_mod == "-") {
+          current_priority--;
+        }
+        // '=' keeps current_priority unchanged
+      }
+
+      std::string priority = std::to_string(current_priority);
+
       // Convert beat notation to time
       std::string start_time = convert_to_time(start, bpm);
       std::string end_time = convert_to_time(end, bpm);
-- 
cgit v1.2.3