Fountain+ syntax guide
This is a guide to an extension of the standard screenplay format
fountain that, hopefully, will be useful to animators. This is a work in progress (currently at version 0.9.0). For one fountain+ example,
click here. For the corresponding animation, check out this touching love story:-),
Lucy meets Lenny (youtube, 71 seconds).
The basic idea is to hide carefully crafted syntax that AI video generators (such as flow or kling) can use for generating accurate animations. The [[ KEY: value ]] notes are embedded in the fountain file so they can be read by the converter (fountain2pam, which uses new python functions as well as the parsing of screenplain) to filter out prop, motion cues, and other blocking information. These fountain+ additions are valid fountain notes (hidden by standard renderers such as highland or screenplain or afterwriting), so they do not interfere with the standard screenplay format.
In other words, fountain+ exists to enrich and extend 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.
The guide below was written with the help of sonnet 4.6 (anthropic) and chatGPT (openai).
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 |
