summaryrefslogtreecommitdiff
path: root/doc/SEQUENCE.md
diff options
context:
space:
mode:
authorskal <pascal.massimino@gmail.com>2026-02-05 00:15:00 +0100
committerskal <pascal.massimino@gmail.com>2026-02-05 00:15:00 +0100
commit873fa985bb4b3ec3841fa77adc16a99184cb9507 (patch)
treede047f4045c81314327c20d85c00e552640874d2 /doc/SEQUENCE.md
parent458b00d254f5e3b1fece6e57462769ce43c96a72 (diff)
feat: Replace explicit priorities with stack-based priority modifiers
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.
Diffstat (limited to 'doc/SEQUENCE.md')
-rw-r--r--doc/SEQUENCE.md53
1 files changed, 36 insertions, 17 deletions
diff --git a/doc/SEQUENCE.md b/doc/SEQUENCE.md
index 05cdc93..614339e 100644
--- a/doc/SEQUENCE.md
+++ b/doc/SEQUENCE.md
@@ -79,17 +79,26 @@ SEQUENCE <global_start> <priority> [optional_end]
### EFFECT Declaration
```
-EFFECT <EffectClassName> <local_start> <local_end> <priority> [constructor_args...]
+EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...]
```
**Parameters:**
+- Priority modifier (one of):
+ - `+`: Increment priority (or start at 0 if first effect)
+ - `=`: Keep same priority as previous effect
+ - `-`: Decrement priority (or start at -1 if first effect, for background layers)
- `EffectClassName`: C++ class name (must be declared in `demo_effects.h`)
- `local_start`: Start time relative to sequence start (beats or seconds)
- `local_end`: End time relative to sequence start (beats or seconds)
-- `priority`: Render order within sequence (lower = drawn first/background)
- - Negative priorities draw behind everything
- `constructor_args`: Optional additional parameters (rarely used)
+**Priority System:**
+- Effects are assigned priorities based on their order in the file
+- First effect: `+` starts at 0, `-` starts at -1, `=` starts at 0
+- Subsequent effects: `+` increments, `=` keeps same, `-` decrements
+- Priorities determine render order (lower = drawn first/background)
+- Effects should be listed in desired priority order within each sequence
+
---
## Time Notation
@@ -223,36 +232,46 @@ White flash on strong beat hits.
### Basic Sequence
```
SEQUENCE 0 0
- EFFECT FlashEffect 0.0 0.5 1 # Starts immediately, runs 0.5s, priority 1
- EFFECT HeptagonEffect 0.2 10 0 # Starts at 0.2s, runs until 10s, priority 0
+ EFFECT + FlashEffect 0.0 0.5 # Priority 0 (first with +)
+ EFFECT + HeptagonEffect 0.2 10 # Priority 1 (increment)
+```
+
+### Same Priority (Layered Effects)
+```
+SEQUENCE 0 0
+ EFFECT + Flash 0.0 0.5 # Priority 0
+ EFFECT = Fade 0.1 0.3 # Priority 0 (same as Flash)
+ EFFECT + Other 0.2 3 # Priority 1 (increment)
+```
+
+### Background Elements
+```
+SEQUENCE 0 0
+ EFFECT - FlashCube 0 10 # Priority -1 (background)
+ EFFECT = BgEffect 0 5 # Priority -1 (same layer)
+ EFFECT + MainEffect 0 10 # Priority 0 (foreground)
```
### Sequence with Explicit End Time
```
SEQUENCE 8b 0 [5.0]
- EFFECT ParticlesEffect 0 120 1 # Would run 120s, but sequence ends at 5s
+ EFFECT + Particles 0 120 # Would run 120s, but sequence ends at 5s
```
### Post-Processing Chain
```
SEQUENCE 0 10
- EFFECT GaussianBlurEffect 0 60 1 # Applied first
- EFFECT ChromaAberrationEffect 0 60 2 # Applied second
- EFFECT SolarizeEffect 0 60 3 # Applied last
-```
-
-### Background Element
-```
-SEQUENCE 0 0
- EFFECT FlashCubeEffect 0 10 -1 # priority -1 = background layer
+ EFFECT + GaussianBlur 0 60 # Priority 0 (applied first)
+ EFFECT + ChromaAberration 0 60 # Priority 1 (applied second)
+ EFFECT + Solarize 0 60 # Priority 2 (applied last)
```
### Music-Synchronized Effects
```
# BPM 120
SEQUENCE 0b 0 # Start at beat 0 (0.0s)
- EFFECT FlashEffect 0b 1b 1 # Flash from beat 0 to beat 1 (0-0.5s)
- EFFECT HeptagonEffect 4b 8b 0 # Main effect from beat 4 to 8 (2-4s)
+ EFFECT + Flash 0b 1b # Flash from beat 0 to beat 1 (0-0.5s)
+ EFFECT + Heptagon 4b 8b # Main effect from beat 4 to 8 (2-4s)
```
---