A fountain+ guide

Fountain+ syntax guide

[[ KEY: value ]] notes embedded in the Fountain file are read by the converter. They are valid Fountain notes (hidden by standard renderers), so they do not affect standard screenplay formatting.

Fountain+ exists to enrich a standard .fountain screenplay so that fountain2pam.py can generate both better PAM JSON blocking and higher-quality AI video prompts (https://github.com/wdjoyner/pam). The idea is simple: put richer production metadata into the screenplay file itself so the same source file can drive PAM animation, prompt generation, and later video assembly.

Basic syntax

[[ KEY: value ]]

Notes may span multiple lines:

[[ KEY: first line
   continuation line ]]

Keys are case-insensitive and terminate at the first colon.

Supported keys

Key	Scope	Effect
MOOD	Scene	Visual tone appended to every subscene prompt
SCENE POPULATION	Scene / mid-scene	Character presence note for AI prompt generation
NEGATIVE	Scene / mid-scene	Negative prompt text
CAMERA	Scene / mid-scene	Camera direction override
KIND	File	Species/type template for character descriptions

MOOD

Use MOOD immediately after a scene heading to specify visual tone, lighting, palette, and general emotional register for all subscenes in that scene.

INT. VENUS CITY OBSERVATORY - NIGHT

[[ MOOD: cool blue-green, holographic, bureaucratic-noir ]]

Use 3–5 strong descriptive terms rather than vague labels.

SCENE POPULATION

Use SCENE POPULATION to tell the converter which characters are present at a given point in the scene. This is especially useful for AI video generation, because it helps prevent missing or hallucinated characters in a shot.

[[ SCENE POPULATION: Governor, Sidel. No other characters. ]]

Update it whenever characters enter or exit:

[[ SCENE POPULATION: Governor, Sidel, then Nona enters. ]]

[[ SCENE POPULATION: Sidel, Nona only. Governor exits here. ]]

In practice, this works best when paired with an updated NEGATIVE note so the active prompt and the “do not render” guidance stay aligned.

NEGATIVE

Use NEGATIVE to supply explicit negative-prompt text for image or video generators.

[[ NEGATIVE: No additional human figures. No crowd. No extras.
   No faces on the dodecahedron. ]]

Update it after entrances or exits:

[[ NEGATIVE: No dodecahedron. No geometric objects.
   No additional human figures. ]]

CAMERA

Use CAMERA when you want to override the converter’s default shot choice.

[[ CAMERA: Wide establishing shot. ]]

[[ CAMERA: slow push in toward the Governor during this exchange ]]

[[ CAMERA: over-the-shoulder from Sidel's perspective ]]

When CAMERA is present, it takes priority over automatic camera heuristics.

KIND

KIND defines a reusable species/type template for character appearance. Place these notes anywhere in the file; they are file-level, not tied to a single scene.

[[ KIND: Venusian | short, green-skinned humanoid, wide-waisted,
   large dark eyes, minimal body hair ]]

[[ KIND: talking dog | four-legged, golden retriever coloring,
   expressive face, wears a small bow tie ]]

Tag a character with a kind on the intro line:

NONA SONNOF [Venusian] — short, early 50s, formidable...
RAMIS [Dog], a compact robot dog with silver-grey joints, trots in.

The converter uses the kind template as a species/type baseline and combines it with the character’s own description.

Prop-character routing via [Kind]

Characters tagged as non-humanoid or special prop-characters can be routed to non-HumanGraph representations when appropriate.

RAMIS [Dog], a compact robot dog with silver-grey joints, trots in.

This allows dialogue to route to prop_say and movement to the proper non-humanoid action such as trot_to.

Complete scene opening example

INT. VENUS CITY OBSERVATORY - NIGHT

[[ MOOD: cool blue-green, holographic, bureaucratic-noir ]]
[[ SCENE POPULATION: Governor, Sidel. No other characters
   until Nona enters at her cue. ]]
[[ NEGATIVE: No additional human figures. No crowd. No extras.
   No faces on the dodecahedron. ]]

The room is a domed observatory. Cool blue-green light from slowly
orbiting holographic planets. Foreground: a long conference table
with a computer terminal. Background: two robot sentinels at sealed
blast doors, status lights blinking amber.

Practical guidance for stronger prompts

1. Put MOOD under the scene heading

Use 3–5 words covering palette, lighting style, and emotional register.

INT. HOSPITAL CORRIDOR - DAY

[[ MOOD: cold white fluorescent, clinical, quietly tense ]]

2. Write the opening action block like a cinematographer

Go near → far, mention the light source early, and end on the overall mood impression.

The room is a domed observatory. Cool blue-green light from slowly
orbiting holographic planets. Foreground: a long conference table
with a computer terminal. Midground: star maps covering the curved
walls. Background: two robot sentinels at sealed blast doors,
status lights blinking amber. The air feels bureaucratic and
slightly ominous.

3. On character introduction, give build/age, wardrobe, and posture

SERGEANT SIDEL [Venusian] — compact, mid-40s, the kind of face
that has followed orders for twenty years and found it agreeable.
Classic Venusian military dress uniform: deep cobalt blue, high
collar, gold piping at the shoulders and cuffs, regulation boots.
Stands at attention: chin up, arms at sides, eyes forward.

4. For prop-characters, describe size, surface, glow behavior, and states

The GOVERNOR OF VENUS — a slowly rotating dodecahedron roughly the
size of a basketball, hovering at eye level above the conference
table. Translucent gold, glowing from within. Each face catches
light differently as it turns. It pulses brighter when speaking.
It goes amber-orange in low-power mode. It goes dark when it exits.
It has no face and needs none.

5. For entrances, describe silhouette, wardrobe, entrance energy, and first gesture

NONA SONNOF [Venusian] — short, early 50s, formidable in the way
that small objects under high pressure are formidable. Futuristic
Venusian business suit: structured but fluid, deep charcoal with
subtle iridescent trim that shifts color in the light. She sweeps
in through the blast doors with the energy of someone who owns
every room she enters.

6. Use parentheticals for gaze or body orientation, not just tone

NONA
(not looking at Sidel — eyes on the Governor)
Every time one fails, the hospital fills up.

7. For “unanimatable” lines, write what the camera sees

A beat. The holographic Earth diagram pulses quietly behind them.
Nobody moves. The room hums.

Anything PAM cannot map directly into blocking may still enrich the AI prompt output.

8. For prop color changes, include color, motion change, and dramatic meaning

The dodecahedron's glow dims from gold to a flat amber-orange.
Its rotation slows. A power-conservation mode — the AI equivalent
of someone putting a hand up and saying "one moment."

9. For on-screen text, add a lead-in line

The dodecahedron's surface turns a corporate amber. Then, in
clean sans-serif:

> PLEASE WAIT...
> THE GOVERNOR OF VENUS
> WILL BE RIGHT WITH YOU.

10. End scenes with a clear final image

Describe what still moves and what emotional scale remains.

Nona stares at the empty air where the Governor was. The
holographic planets continue their silent orbits above her.
She looks very small in the room.

Quick reference card

What you're writing	Rule of thumb
Scene heading	Put [[ MOOD: ... ]] immediately below
Species / type	Use [[ KIND: name | description ]] anywhere in file
Character intro	[Kind] tag, then build/age, wardrobe, posture
Prop-character intro	size, surface, glow behavior, color states
Entrance	silhouette, wardrobe, entrance energy, first gesture
Parenthetical	eye contact or body orientation, not just tone
Unanimatable action	write what the camera sees
Prop color change	color, motion change, dramatic meaning
On-screen text	add a context lead-in line
Final image	say what remains moving and what the emotional scale is
Population change	update SCENE POPULATION and NEGATIVE together
Camera override	add [[ CAMERA: ... ]] before the relevant beat
Small accessories	remove if they cause generator inconsistency

Subscene prompts

The --prompts output contains per-subscene video prompts in a four-paragraph cinematic format:

[SHOT / CAMERA]          — framing and camera movement
[SETTING / ATMOSPHERE]   — environment, lighting, mood
[CHARACTERS & ACTION]    — who does what, in what order
[DRAMA / CUT]            — what the scene is building toward

Clip modes:

Mode	Boundary rule	Best for
per-speaker (default)	New clip per speaker change	Kling and similar
timed	Drama-aware 5–10 second windows	Strong-consistency generators