Write a panel as a comic script#

Comic writers already have a format. It is not YAML, it has been in use for decades, and asking someone to abandon it in order to try a compiler is a poor trade.

So Scenet reads it.

umbrella.script#
---
cast:
  ALICE: {reference: alice, at: left_third}
  BOB:   {reference: bob,   at: right_third, facing: left}
---

PAGE ONE

PANEL 1
@shot: full_shot
CAPTION: Midnight. The docks.
Alice and Bob face each other on a rainy street corner. She is exasperated.

ALICE
You forgot your umbrella!

BOB
I know.

PANEL 2
@shot: medium_close_up
Closer now. Bob will not meet her eye.

BOB (whisper)
I left it on purpose.

ALICE (shouting)
You what?!

The lines between the --- fences are the front matter: who ALICE and BOB are, which a script has no way to say. Everything under them is the script as a writer writes it. Save that as umbrella.script and compile it exactly like any other document:

scenet build umbrella.script --strip

The gallery’s examples/gallery/13-comic-script.script is a script like it: open it in the playground. Each convention below has an example of its own there, written the way writers who use it write.

The rules#

Line

Means

PANEL 1

Starts a new panel. PANEL 1:, PANEL 1. and Panel One are the same panel.

Panel 1. Alice and Bob on a corner.

Dark Horse’s form: the panel, and its description on the same line.

@shot: full_shot

A directive. @shot and @angle set the camera; anything else sets a top-level panel key. Each is written once per panel: a second is reported, not quietly kept.

ALICE (all caps, alone)

The lines after it, up to a blank line, are one speech by ALICE.

BOB (small)

Muttered: smaller type, in a balloon that keeps its room. (weak) is the same.

BOB (whisper)

Same, with a balloon kind: (whisper) or (whispering), (shout), (shouting), (yell) or (yelling), (thought) or (thinking). (burst) is a shout. Several parentheticals, or one with commas, are read together.

ALICE: Hello.

A cue with its line on the same line. Dialogue when ALICE is in the panel’s cast; see below.

ALICE (V.O.)

A voice over: the line is a spoken caption by ALICE, not a balloon. (VO) and (VOICE OVER) too.

ALICE (OP)

Dark Horse’s off-panel speech: Alice is left out of this panel, and her balloon’s tail ends on the frame. (OFF), (off-panel), (O.S.) and (O.C.) too.

ALICE (OP, left)

Same, from the side named: left, right, top or bottom. A side alone is a note for the artist.

CAPTION: Midnight., CAP: Midnight.

A caption box, its text on the same line.

CAP: or CAPTION (alone)

Dark Horse’s form: the caption’s text is on the lines under it, to a blank line.

CAPTION (monologue): ...

Same, with a caption kind: (locale), (monologue), (spoken) or (editorial). (voice over) is the spoken kind.

CAP/ALICE

Dark Horse’s caption carrying a character’s speech: a spoken caption by ALICE.

1. ALICE:, 2) CAP:

Blambot’s numbered lettering items: the number is set aside.

SFX: BLAM

A sound effect. The sound is on the same line.

SFX (BOB, large): KRAK

Same, coming from BOB, at a size.

SFX: (alone)

Dark Horse’s form: the sound is on the next line.

Anything else

Prose. Preserved, never interpreted.

PAGE ONE

Starts a page: the panels under it are laid out on it. See Pages.

PAGE ONE (five panels)

Dark Horse’s form: the page, and how many panels it has. A count its panels do not match is a panel-count note.

@tiers: 2 1 2

Right after a PAGE heading: how many panels each tier of that page holds, from the top.

## PANEL 2, **PANEL 2**, ---

Markdown: the markers are stripped and the heading read; a horizontal rule is a blank line.

Before the first heading

The title page: the writer’s name and address, the title. Kept, never interpreted.

The one detail that trips people up: a speaker cue is recognised by the name being all caps, not the whole line. BOB (whisper) qualifies, because only BOB is tested. Capitals with accents are capitals: HÉLÈNE and ZOË are cues. The script is read composed (Unicode NFC), so a name your editor stored as a letter and a separate accent is the same name the front matter spells, and a byte-order mark at the start of the file is ignored.

A speech runs until a blank line. Wrap a long line of dialogue wherever you like; the lines are joined with a space into one balloon. A line that looks like another cue ends the speech and starts the next, so two speeches need no blank line between them.

Underline a word by writing it between underscores: I _told_ you. Scripts underline the words to stress, and a letterer sets them in bold italic, which is what the compiler does — in dialogue and in captions alike. The rules are in the language reference.

Panel numbers may start again on each page, as publishers’ script formats ask. When they do, every panel is named by its page as well: PANEL 1 under PAGE TWO is panel 2-1, and scenet build writes it to name.2-1.svg. A page spelled out in English is named by its number (PAGE TWO is page 2, PAGE TWENTY-ONE page 21); anything else is kept as written (PAGE 3A). A script that numbers its panels straight through keeps the plain names. Two panels that would still share a name, such as PANEL 1 twice on one page, are reported as duplicate-panel rather than one quietly replacing the other.

A sound effect is an SFX line, written where it happens in the script, as publishers ask for everything to be listed in reading order. The parenthetical says who or what it comes from — a name from the cast — and how loud, small, medium or large, in either order. Dark Horse writes SFX: as a cue with the sound under it; that works too, and the line under it is the sound however it looks — BLAM is in capitals, which would otherwise make it a character’s cue. An SFX: cue with nothing under it is reported rather than dropped. Turns, arcs and hollow letters are written in YAML; see sfx.

CAP, CAPTION and SFX are checked before speaker cues, because as far as the cue pattern is concerned each is a perfectly good character name. So they are reserved: none can be a cast member’s id. A caption or a sound effect with its text to follow also wins over a cue waiting for its line — BOB (whisper) then CAPTION: Later. is a caption, and a note says Bob had nothing to say.

A cue may carry its line after a colon, ALICE: Hello., as Dark Horse’s guide itself does. A writer’s note to the artist looks exactly the same — NOTE: redraw the rain — so the line is dialogue only when the name is in the panel’s cast: the front matter’s, and any @cast: in the panel, wherever in it. A name in capitals that is not in the cast is read as it would otherwise be — prose, or a wrapped line of the speech above — and a looks-like-dialogue note says so, since a misspelled speaker looks the same. A name in lower case, Junior: Die, you dirty rat!, is dialogue only when it is exactly a cast member’s id, and otherwise silent prose.

A caption can carry speech. Dark Horse’s CAP/ALICE, with the words in quotation marks, is a spoken caption by ALICE. The compiler letters a spoken caption’s quotation marks itself — one opening each box, one closing the speaker’s last — so the writer’s are taken off rather than doubled, and so is one enclosing pair around a balloon’s text. A voice over, ALICE (V.O.), is the same thing written as a cue: Blambot defines CAPTION (VOICE OVER) as a character “speaking, but … not in the location shown”.

A script as publishers ask for it#

Dark Horse’s script format is the reference house format, and Scenet reads its layout as written:

Part of a script in Dark Horse’s format, less its front matter#
Margo Wren
14 Harbour Lane, Port Ellis

PAGE ONE (two panels)

Panel 1. A lighthouse on a cliff at dusk. Maya climbs the last of the steps.

MAYA:
Theo? The lamp is out --

Panel 2. Inside. Theo kneels by the dead lamp.

THEO (whisper):
-- because somebody forgot the oil.
  • The title page is everything before the first heading. It is kept and never read, as prose is. A name in capitals with a line under it looks like a cue, so it is pointed out as a looks-like-dialogue note; a name from the cast there is an error, since it is far more likely a missing PANEL heading. A directive, a caption or a sound effect before the first heading belongs to no panel, and is an error.

  • A line between a PAGE heading and its first PANEL belongs to the page, never to the last panel of the page before, which is where it used to end up.

  • PAGE ONE (five panels) states the count. When the panels under it number something else, a heading has usually been missed, so it is a panel-count note. Any other parenthetical, (splash) say, is a note to the artist, and is not read as a count.

  • Panel 1. with its description on the same line is a heading when the label looks like a number — digits, digits and a letter, one letter, or a number in words — so that Panel shows Alice. stays the sentence it is.

  • --, Dark Horse’s mark for a speech carried to the next balloon, is kept as written, and is never set at the start of a line or alone on one.

  • A cue with nothing said under it is a looks-like-dialogue note rather than vanishing.

examples/gallery/31-dark-horse.script is a script in this format, title page and all: open it in the playground.

A script kept in Markdown#

Writers keep scripts in Markdown, so # to ###### before a heading, ** or __ around it or around a label, and a horizontal rule are tolerated: the markers are stripped and the convention read. It is not a second format: the text of a line is never rewritten.

Part of a comic script kept in Markdown#
## PAGE ONE

### PANEL 2
**Alice** waits on the corner, soaked.

**alice:** You forgot your _umbrella_.

---

**PANEL 3**
  • A rule, ---, *** or ___, is a blank line, and parts two panels as one does.

  • A name in lower case is a cue when it is a cast id, written with its line after the colon: alice: speaks when the front matter casts alice, as a YAML panel would. Alone on its line, a name is a cue only in capitals.

  • A word between underscores is stressed, in the lettering. In prose, Markdown’s markers round a word are taken off the description a screen reader is given.

examples/gallery/63-a-markdown-script.script is a script kept this way, with a cover panel before its first PAGE heading: open it in the playground.

A letterer’s script#

Blambot’s comic script basics asks writers to number every item a letterer letters, in reading order, and to say what each is. Scenet reads it so:

  • 1., 2) before a label is a lettering item’s number, and is set aside.

  • A caption’s kind in parentheses: (locale), (monologue), (spoken), (editorial), and Blambot’s CAPTION (VOICE OVER), which is the spoken kind.

  • A balloon’s kind: (OFF) from outside the panel, with the side it comes from; (WEAK), said faintly, in smaller type; (BURST), shouted.

  • A sound where it happens: SFX: with the sound on the line under it, its size in the parenthetical, SFX (small):.

examples/gallery/68-a-letterers-script.script is a page of one: open it in the playground.

Written like a screenplay#

A writer coming from film writes a cue as a screenplay does, a name in capitals alone on its line with an extension after it, and Scenet reads the extensions it can letter:

  • (V.O.), or (VOICE OVER), is a voice over: a spoken caption by the speaker. CAPTION (V.O.) is one nobody is named for.

  • (O.S.), and the older (O.C.), is somebody heard from off screen, here off panel, from the side the parenthetical names: KEEPER (O.S., left).

  • (CONT'D), (beat) and any word Scenet does not letter by is a note for the artist.

Two habits change. A screenplay puts a parenthetical such as (whispering) on the line under the cue; in a comic script that line is what is said, so the parenthetical goes on the cue’s line. And a slugline in capitals alone on its line looks like a cue, so write the panel’s description after it on the same line: INT. LIGHTHOUSE - NIGHT. Maya by the dead lamp.

examples/gallery/67-written-like-a-screenplay.script is one, whose last panel recasts the scene with @cast and @staging: open it in the playground.

Pages#

Each PAGE heading is a page, and the panels under it are laid out on it, as a scene’s pages: would lay them out. Dark Horse leaves “exact panel layout” to the artist, and here the compiler is the artist, so a page’s panels go into tiers by a fixed rule, in reading order:

Panels

Tiers, top to bottom

1

1

2

1, 1

3

1, 1, 1

4

2, 2

5

2, 1, 2

6

2, 2, 2

7

2, 3, 2

8

3, 2, 3

9

3, 3, 3

more

rows of three, the extra panels in the earlier tiers: 10 is 3, 3, 2, 2

Three tiers is the most up to nine panels, because a page’s lettering height assumes three; an odd panel takes a tier of its own in the middle, where a beat sits best.

Say otherwise with @tiers:, written right after the PAGE heading and before its first panel:

Part of a comic script#
PAGE TWO
@tiers: 1 2

PANEL 1
...

That page’s first panel takes the top tier alone, and the next two share the one under it. The counts must add up to the page’s panels; when they do not, or @tiers: is written anywhere else, it is a page-layout error at its line. Anything finer — a panel twice as wide, a tier taller than the rest, columns, insets, slants, a panel that bleeds past the trim — is a scene’s pages:; see Compose a page.

The front matter’s page: sets the format every page shares: its size, margin, gutters and bleed. A script has no pages: key — its pages are its PAGE headings — so writing one is an error.

  • A panel on a page is compiled at the size of its frame, and every panel on it letters at one size, as on any page. The front matter’s panel: {size: ...} still sizes panels that are on no page.

  • Panels before the first PAGE heading are on no page. They compile on their own, as every panel of a script without PAGE headings does.

  • Page files are numbered by position: scenet build story.script writes the first page to story.page-1.svg whatever its heading says, so an excerpt that starts at PAGE SEVEN still writes page-1. Each panel is written on its own as well, as before.

A manga, right to left#

direction: rtl in the front matter makes the whole script read from the top right, as a manga is read: the panels of each page, and the balloons of each panel. Nothing is mirrored. A character written at right_third stands on the right; only what reading decides follows the direction, as direction explains.

Part of a manga script#
---
direction: rtl
page: {size: [1280, 1820], margin: 64, gutter: 24, tier_gutter: 36}
---

PAGE ONE (splash)

(splash) is a note for the artist, not a count. A manga script numbers each page’s panels from 1 again, which names them by page, 2-1 to 2-4, and @over: 1 on page two is panel 2-1.

examples/gallery/64-a-manga-script.script is two pages of one, the first in colour: open it in the playground.

French scripts#

A Franco-Belgian script is read in its own words. The vocabulary is the Cité internationale de la bande dessinée’s:

French

Means

PLANCHE 1 (six cases)

A page, and its count — cases or vignettes, in digits or words to vingt

CASE 2, VIGNETTE 2, Case 2 : La plage.

A panel. Followed by a number only: CASE alone is a word, and a cue

RÉCITATIF :, CARTOUCHE :, NARRATIF :

A caption, exactly as CAPTION: — its kind in the parenthetical, /NAME for speech

ONOMATOPÉE : FLOP

A sound effect, as SFX:

LÉA : « Bonjour. »

A cue and its line. The space before the colon may be a no-break space, and the guillemets are taken off

(pensée), (off), (hors champ)

A thought balloon; off-panel speech

(murmure), (chuchoté); (cri), (crié)

A whisper; a shout

(à voix basse)

Small type, as (small)

Récitatif, cartouche and narratif all name the caption box itself (Cité; Alloprof’s “cartouche (ou récitatif)”; the BnF), which is why they are aliases of CAPTION rather than a kind of their own: the parenthetical says what the box is doing, CARTOUCHE (monologue) for a character’s thoughts.

The delivery words are the ones a source defines. The BnF’s sheet on balloons draws a dotted outline for a character who murmure — chuchoter is to murmur, in Larousse — capitals and bold for one who crie, and smaller type for one who parle bas. Any other word, (hurlé) say, stays a note to the artist, as an English one does.

examples/gallery/33-planche.script is a planche written in French: open it in the playground.

Shots and angles in French#

Shots and angles may be written in French, in a comic script’s @shot: and @angle: only — the YAML language and its schema stay in English. Case, accents, apostrophes and hyphens do not matter, and the usual abbreviations are read: GP, P.A.. The échelle des plans maps rung for rung onto the shot ladder:

French

Abbreviation

Cuts

shot

plan d’ensemble

PE

the setting, figures small

long_shot

plan moyen

PM

head to foot

full_shot

plan américain

PA

mid-thigh

cowboy

plan rapproché taille, plan mi-moyen

PRT, PMM

the waist

medium_shot

plan rapproché poitrine, plan rapproché

PRP, PR

the chest

medium_close_up

plan rapproché épaule, plan épaule

the shoulders

close_up

gros plan

GP

the face

big_close_up

très gros plan

TGP

a detail

extreme_close_up

Gros plan is big_close_up because the French sources put its cut above the shoulders, at the face: the BnF’s Créer une BD (“coupé souvent au-dessus des épaules… s’attache au visage”), the Lyon academy’s sheet (at the neck), and French Wikipedia’s ladder, which has its own plan rapproché épaule between plan rapproché and gros plan. Quebec’s OQLF defines gros plan at the shoulders instead; writing plan rapproché épaule gets that framing. Plan général and plan italien have no rung of their own, and medium_full no French name; none is invented. The angles are plongée (high), contre-plongée (low) and angle normal (eye_level).

Two planches in the gallery walk the ladder from the farthest shot to the nearest: examples/gallery/65-french-shots-abbreviated.script in abbreviations, from PE to TGP (open it in the playground), and examples/gallery/66-french-shots-in-full.script vignette by vignette, every name in full (open it in the playground). The nearest shots letter nothing: the head fills the panel, and no balloon may cover a face.

Off-panel speech#

Dark Horse writes CHARACTER (OP): for a character “speaking from off-panel”; Blambot writes (OFF), and screenplays (O.S.) or the older (O.C.). All four mean the same here: the line is spoken by somebody who is not drawn, and the balloon’s tail ends on the frame, on their side — see off-panel speech.

Off panel means in the scene but out of the frame, and the front matter is the scene’s cast. So ALICE (OP) leaves Alice out of that panel: out of its cast, and out of every staging relation that names her — ALICE left_of BOB does not apply there, and a dropped-relation note says so. All but one: BOB looking_at ALICE still holds, and Bob turns toward the side she is heard from. Her tail ends on the side she was written to stand on, at: left_third being the left, unless the cue names one: ALICE (OP, right). Somebody never cast — PHONE (OP) — is heard just the same, from the side nearer the balloon.

A panel whose own @cast: draws her, or in which she speaks both on and off panel, is off-panel-speaker. A panel @over: hers does not inherit her absence: it is worked out from each panel’s own lines.

To leave somebody out of a panel who says nothing in it, write @cast: {BOB: null} there. As in YAML, the relations that name him go with him, each with a dropped-relation note. Written for somebody who then speaks (OP), it says the same as the cue alone.

One panel over another#

Consecutive panels share nearly everything — the place, the weather, who stands where — and restating it is where continuity errors get in. @over: writes a panel as a change to another, exactly as over: does in a YAML scene:

Part of a comic script#
PANEL 1
@shot: full_shot
@setting: {place: docks, weather: rain}

PANEL 2
@over: 1
@shot: close_up

Panel 2 inherits panel 1’s directives and replaces its shot. It never inherits dialogue: each panel’s lines are its own. A label is looked up on the same page first, so @over: 1 on page two is panel 2-1, and then as a panel’s whole name, 1-3. It may name a panel further down. A panel that does not exist, a cycle, or a panel over itself is one composition finding, at the @over: line.

Prose is never interpreted#

“Alice and Bob face each other on a rainy street corner” is not parsed, not natural-language-processed, and does not affect the output in any way. It is kept because a script is a document people read, and stripping the description would make the file worse for its primary audience.

If you want the rain, say so with a directive: @setting: {weather: rain} draws it. The description beside it is never read by the compiler.

It is read by people, though, and not only the artist: a panel’s prose is its description, what accessible output reads to somebody who cannot see the panel. Its lines become one paragraph, and Markdown’s markers round a word (**Alice**, _up_) are taken off. Everything the prose says is read — a note to the artist, NOTE: redraw the rain., included — so when the reader should hear something else, write it as a directive, which is kept exactly as written and wins over the prose:

Part of a comic script#
PANEL 1
@description: Alice waits on a corner in the rain.
NOTE: redraw the rain, heavier.

A panel drawn @over: another does not inherit its prose: it is a different picture. A description in the front matter is refused, since every panel would inherit it. A line of prose holding a character an SVG cannot hold is reported at that line.

Front matter#

A script is dialogue and camera direction. It has no way to say who ALICE is, which puppet she uses, or where she stands. That comes from a YAML preamble between --- fences:

Part of examples/gallery/13-comic-script.script#
---
panel:
  size: [900, 700]
cast:
  ALICE: {reference: alice, pose: pointing,     at: left_third}
  BOB:   {reference: bob,   pose: arms_crossed, at: right_third, facing: left}
staging:
  - ALICE left_of BOB
  - ALICE looking_at BOB
  - ALICE ground_shared_with BOB
---

PAGE ONE

PANEL 1
...

Everything in the front matter is a default every panel inherits — exactly the same mechanism as shared defaults in a sequence — and so a description, which says what one panel shows, is refused there.

direction: rtl there makes the whole script read from the top right, as a manga does; see direction. It is the script’s, never one panel’s, so @direction: under a PANEL heading is refused.

Note the actor ids are written in caps here, to match the speaker cues. That is a convention, not a requirement; the ids simply have to agree.

From Python#

from scenet import parse_script

panels = parse_script("""---
cast:
  ALICE: {reference: alice}
---

PANEL 1
@shot: close_up
A quiet room.

ALICE
Is anyone there?

PANEL 2
ALICE (whisper)
Anyone?
""")

# Panels are named by the number in their heading.
assert list(panels) == ["1", "2"]
assert panels["1"].camera.shot.value == "close_up"
assert panels["1"].script[0].text == "Is anyone there?"

# The prose line is interpreted nowhere: it is the panel's description, as written.
assert panels["2"].script[0].kind.value == "whisper"

Panel names come straight from the heading, so PANEL 1 becomes "1". The CLI uses them as filename suffixes: umbrella.script compiles to umbrella.1.svg, umbrella.2.svg.

parse_script gives you IR; load_script reads a file; and compile_document dispatches on the .script extension so you do not have to care.

The front matter is not optional in practice#

A script with no cast will not parse at all. Validation is total, so a speaker cue naming somebody who is not in the cast is an error at parse time rather than a blank balloon discovered later:

from scenet import ScriptSyntaxError, parse_script

try:
    parse_script("PANEL 1" + chr(10) + "ALICE" + chr(10) + "Hello.")
except ScriptSyntaxError as exc:
    assert "unknown actor" in str(exc)
    assert "ALICE" in str(exc)

That is the first error you will hit when adapting an existing script: every speaker cue needs a matching entry in the front-matter cast.

Both frontends produce the same IR#

This is the point of the whole arrangement. script_front computes no coordinates and knows nothing about geometry; it produces the same PanelIR the YAML frontend does, and everything downstream is unaware that a second syntax exists.

Adding a third syntax means adding a parser and one line in the extension table. Nothing else changes.