# The Prelude

You can define words in any step and they become available to all other steps. But as a project grows, definitions get scattered across steps and become hard to find and maintain. The **prelude** is a dedicated place for this. It is a project-wide Forth script that runs once before the first step plays. Definitions, variables, settings — everything in one place. Press `d` to open the prelude editor. Press `Esc` to save and close. Press `D` (Shift+d) to re-evaluate it without opening the editor.

## Naming Your Sounds

The most common use of the prelude is to define words for your instruments. Without a prelude, every step that plays a bass has to spell out the full sound design or to create a new word before using it:

```forth
pulse sound 0.8 gain 400 lpf 1 lpd 8 lpe 0.6 width .
```

Repeat this across eight steps without making a new word and you have eight copies of the same thing. Change the filter? Change it eight times.

In the prelude, define it once:

```forth
: bass pulse sound 0.8 gain 400 lpf 1 lpd 8 lpe 0.6 width . ;
```

Now every step just writes `c2 note bass`. Change the sound in one place, every step follows.

A step that used to read:

```forth
pulse sound c2 note 0.8 gain 400 lpf 1 lpd 8 lpe 0.6 width .
```

Becomes:

```forth
c2 note bass
```

## Building a Vocabulary

The prelude is where you build the vocabulary for your music. Not just instruments but any combination of code / words you want to reuse:

```forth
;; instruments
: bass pulse sound 0.8 gain 400 lpf 1 lpd 8 lpe 0.6 width . ;
: pad sine sound 0.5 gain 2 spread 1.5 attack 0.4 verb . ;
: lead tri sound 0.6 gain 5000 lpf 2 decay . ;

;; musical helpers
: octup 12 + ;
: octdn 12 - ;
: quiet 0.3 gain ;
: loud 0.9 gain ;
```

By using the prelude and predefined words, steps become expressive and short. The prelude carries the design decisions; steps carry the composition.

## Setting Initial State

The prelude also runs plain Forth, not just definitions. You can use it to set variables and seed the random generator:

```forth
c2 !root
0 !mode
42 seed
```

Every step can then read `@root` and `@mode`. And `42 seed` makes randomness reproducible — same seed, same sequence every time you hit play.

## When It Runs

The prelude evaluates at three moments:

1. When you press **Space** to start playback
2. When you **load** a project
3. When you press **D** manually

It runs once at these moments, not on every step. This makes it the right place for definitions and initial values. If you edit the prelude while playing, press `D` to push changes into the running session. New definitions take effect immediately; the next time a step runs, it sees the updated words.

## What Not to Put Here

The prelude has no access to sequencer state. Words like `step`, `beat`, `iter`, and `phase` are meaningless here because no step is playing yet. Use the prelude for definitions and setup, not for logic that depends on timing. The prelude also should not emit sounds. It runs silently — any `.` calls here would fire before the sequencer clock is running and produce nothing useful.
