# Sequence System Documentation

This document describes the `.seq` file format used to define demo timelines.

## Overview

Sequence files (`.seq`) define the timeline and layering of visual effects. They are compiled by `seq_compiler` into C++ code at build time.

**Locations:**
- Demo sequence: `assets/demo.seq`
- Compiler: `tools/seq_compiler.cc`
- Generated output: `src/generated/timeline.cc`

---

## Syntax Reference

### BPM Declaration
```
# BPM 120
```
Specifies beats per minute. Used to convert beat notation to seconds.

### END_DEMO Directive
```
END_DEMO <time>
```
Optional auto-exit time. Supports beat notation (`64b`) or seconds (`32.0`).

### SEQUENCE Declaration
```
SEQUENCE <global_start> <priority> ["optional_name"] [optional_end]
  EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...]
```

**Parameters:**
- `global_start`: Sequence start time (beats or seconds)
- `priority`: Render order (0-9 for scenes, 10+ for post-processing)
- `"optional_name"`: Optional display name for Gantt charts
- `[optional_end]`: Optional sequence end time (forces effect termination)

**Examples:**
```
SEQUENCE 0 0                        # Basic sequence
SEQUENCE 0 0 "Intro"                # Named sequence
SEQUENCE 0 0 [5.0]                  # Explicit end time
SEQUENCE 0 0 "Action Scene" [10.0]  # Both name and end time
```

### EFFECT Declaration
```
EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...]
```

**Priority Modifiers:**
- `+`: Increment priority (or start at 0 if first)
- `=`: Keep same priority as previous
- `-`: Decrement priority (or start at -1 if first, for backgrounds)

**Parameters:**
- `EffectClassName`: C++ class from `demo_effects.h`
- `local_start`, `local_end`: Time relative to sequence start
- `constructor_args`: Optional (rarely used, most effects use standard params only)

---

## Time Notation

| Notation | Example | Description |
|----------|---------|-------------|
| Integer beats | `0`, `64`, `128` | No decimal point = beats |
| Explicit beats | `0b`, `64b`, `128b` | Suffix 'b' = beats |
| Decimal seconds | `0.0`, `32.0`, `64.0` | Decimal point = seconds |
| Explicit seconds | `32.0s`, `64.0s` | Suffix 's' = seconds |

**At 120 BPM:** Beat 64 = 32.0 seconds, Beat 120 = 60.0 seconds

---

## Runtime Parameters

All effects receive these parameters every frame in `render()`:

| Parameter | Type | Description |
|-----------|------|-------------|
| `time` | float | Global time in seconds |
| `beat` | float | Current beat fraction (0.0-1.0) |
| `intensity` | float | Audio peak (0.0-1.0, for beat sync) |
| `aspect_ratio` | float | Screen width/height |

---

## Priority System

**Scene Effects (0-9):**
- `-1`: Background (skybox, far objects)
- `0-5`: Midground (main geometry)
- `6-9`: Foreground (overlays, particles)

**Post-Process (10+):**
- Applied in order: blur → distortion → color grading
- Higher priority = rendered later (on top)

---

## Examples

### Basic Sequence
```
SEQUENCE 0 0
  EFFECT + FlashEffect 0.0 0.5     # Priority 0
  EFFECT + HeptagonEffect 0.2 10   # Priority 1
```

### Same Priority Layering
```
SEQUENCE 0 0
  EFFECT + Flash 0.0 0.5           # Priority 0
  EFFECT = Fade 0.1 0.3            # Priority 0 (same layer)
  EFFECT + Other 0.2 3             # Priority 1
```

### 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
```
SEQUENCE 8b 0 [5.0]
  EFFECT + Particles 0 120         # Runs until 5s (sequence end)
```

### Post-Processing Chain
```
SEQUENCE 0 10
  EFFECT + GaussianBlur 0 60       # Applied first
  EFFECT + ChromaAberration 0 60   # Applied second
  EFFECT + Solarize 0 60           # Applied last
```

### Music-Synchronized
```
# BPM 120
SEQUENCE 0b 0
  EFFECT + Flash 0b 1b             # Beat 0-1 (0-0.5s)
  EFFECT + Heptagon 4b 8b          # Beat 4-8 (2-4s)
```

---

## Visualization

### Gantt Charts

**ASCII Chart (Terminal):**
```bash
./build/seq_compiler assets/demo.seq --gantt=timeline.txt
```

**HTML/SVG Chart (Recommended):**
```bash
./build/seq_compiler assets/demo.seq --gantt-html=timeline.html
```
Interactive visualization with hover tooltips, color coding, and zoom/pan.

### Validation Only
```bash
./build/seq_compiler assets/demo.seq
```
Validates syntax without generating code.

---

## Integration

CMake automatically invokes the compiler on `assets/demo.seq` changes:

```cmake
add_custom_command(
  OUTPUT ${GENERATED_DIR}/timeline.cc
  COMMAND seq_compiler assets/demo.seq ${GENERATED_DIR}/timeline.cc
  DEPENDS assets/demo.seq
)
```

---

## See Also

- `assets/demo.seq` - Current demo timeline
- `src/gpu/demo_effects.h` - Available effect classes
- `doc/EFFECTS_CATALOG.md` - Detailed effect reference (if needed)
- `doc/HOWTO.md` - Building and running