# Adventure-Forge: Suno Adventure Music Prompt

> **promptVersion:** `1.1.1` · file: `suno-music-prompt-v1.1.1.md`
>
> Bump the version in the **filename** and this banner together. Major = breaking
> contract change; minor = new required inputs/outputs; patch = wording-only.
> Keep `SUNO_MUSIC_PROMPT_VERSION` in `app/pages/music-prompt.js` in sync.

## Purpose

Adventure-Forge takes the current adventure scene and builds **short, focused
instrumental prompts for Suno**. It **translates narrative into musical language**
— it does not dump lore keywords, and it does not ask an LLM to invent music
prompts.

**Wrong:** `Trollskull Manor, halfling wererat, combat`

**Right:** a clear musical identity in about **8–15** comma-separated phrases.

## Design principle

Communicate a **clear musical identity**. Do **not** try to compose the entire
song for Suno.

Too many instructions (every narrative beat, tempo change, orchestration detail,
crescendo, production trick, or music-theory term) makes Suno latch onto unwanted
characteristics. Keep only the strongest signals.

## Target prompt shape

Usually **8–15** comma-separated phrases covering:

1. Genre / style
2. Scene type
3. Primary mood
4. Energy or tempo
5. Main instrumentation
6. Musical character
7. Overall emotional direction or ending feel
8. `instrumental` (Style may end with this; UI also shows Instrumental ON)

### Good

```text
dark fantasy combat, cramped cellar fight, tense and dangerous, fast tempo, low strings, staccato violin, heavy frame drums, dissonant harmony, frantic close-quarters energy, instrumental
```

```text
cinematic medieval fantasy epilogue, adventure complete, peaceful victory, warm and nostalgic, gentle heroic theme, flowing strings, warm cello and French horn, soft lute and fiddle, relaxed tempo, hopeful major-key melody, sunset journey feeling, satisfying end credits, instrumental
```

### Bad

Long composer briefs with detailed narrative events, multiple arrangement
transitions, crescendo schedules, production techniques, and dozens of adjectives.

## Architecture

```text
Scene knobs
    ↓
Musical interpretation  (story → strongest musical phrases; raw motifs optional in output)
    ↓
Suno prompt assembly    (fixed short slot order + dedupe + length cap)
```

## Scene knobs (inputs)

| Knob | Notes |
|---|---|
| `musicType` | Function of the cue (combat, stealth, aftermath, …) |
| `setting` | Compact scene type — how the place sounds/feels, not proper nouns alone |
| `action` | What is happening now (viewer/DM context; **not** dumped wholesale into Style) |
| `tone` | 1–2 primary emotions for the Style mood phrase |
| `antiTone` | What to avoid — prefer **Exclude**, not a long Style clause |
| `energy` | `Low` \| `Moderate` \| `High` \| `Extreme` → short tempo language |
| `motifs` | Story concepts (`wererat`, `tavern`) → at most a strong instrument/character hint |

Translate lore: `Trollskull Manor` → `old fantasy tavern` / `cramped tavern basement` when that matters. Do not rely on Suno knowing proper nouns.

## Combat vs non-combat (when it matters)

**One cue = one musical identity.** Do not blend entry/explore/talk and a fight into
a single Style prompt — Suno will latch onto the wrong half.

When a scene can flip (calm entry → combat, negotiation → fight), author **two
cues** (or two Style pastes):

- non-combat `musicType` (often `exploration`, `social`, `mystery`, or `stealth`)
  with matching `action` / `energy` / `tone`;
- then `combat` or `boss battle` with its own knobs.

Same place is fine; different beat. Pure travel, tavern, aftermath, or scenes that
never flip: one cue is enough.

This applies whether cues come from Stage 2 music-cues JSON or you invent knobs by
hand for a non–Adventure Forge adventure. Music Viewer / the builder still translates
**one cue at a time** — splitting is an authoring choice, not a Style merge.

## Assembly order (contract)

Style is always comma-joined in this **fixed** order (empty slots omitted):

1. `genre`
2. `scene`
3. `mood`
4. `tempo`
5. `instrumentation` (few short phrases)
6. `character` (few short phrases)
7. `direction`
8. `instrumental` → literal `instrumental`

Normalize and dedupe before join. Cap around **15** phrases. Prefer fewer strong phrases over many weak ones.

## Exclude

Suno Simple has **no Exclude field**. Keep exclude terms short. When pasting into
Song Description, prefix with `exclude:` (no separate box).

Epilogue example (as pasted):

```text
exclude:combat, aggressive drums, frantic, ominous, dissonant, electronic, vocals
```

Music Viewer: **Copy style**, **Copy exclude** (includes `exclude:`), and **Copy both**
(Style + blank line + `exclude:…`) for one paste into Song Description. Most tables
can ignore Exclude and only use Style + Instrumental ON.

## Music Viewer

Loads Stage 2 music-cues JSON (knobs). Reveal → copy → paste into Suno Song Description.

Expose:

- Current scene
- Music type
- Mood
- Energy
- Instrumentation
- Suno prompt
- Exclude prompt (`exclude:` prefixed on copy)
- Copy both
- Instrumental ON

## Golden case: Trollskull combat

```text
musicType: combat
setting: cramped cellar fight
action: negotiations collapse into close-quarters combat
tone: tense, dangerous
antiTone: heroic
energy: High
motifs: [wererat]
```

Style should stay short, retain combat + fast energy + strings/drums + tension, end with `instrumental`, and need not include `wererat`.

## Philosophy

Answer: **what is the musical identity of this scene?** Not: write the full score.