Diagnostics#

Everything scenet check reports and every note the compiler gives, each with an entry: what it says, why it happens, how to fix it, the keys that can give it and the release it was first given in – then a document that gives it, what the command line prints of that document, and the same document fixed. Every document on this page is checked by the test suite: the first of each pair gives exactly that diagnostic, and its fixed twin gives nothing at all.

The ids are stable across releases. A report prefixes a rule’s id with scenet/, as scenet/unknown-key; SARIF links each rule here, from its helpUri. A compile note’s name is what a gallery example’s notes: declares it by. The documents name pictures, fonts and a puppet the gallery has beside it, which the playground has beside every document it opens.

At a glance#

Id

Level

Says

artwork-contract

error

A picture’s artwork contract cannot be read

balloon-placement

error

A balloon or caption has no legal position

caption-speaker

error

A caption that is not spoken names a speaker

composition

error

An over: chain cannot be resolved

conflicting-cast

error

A cast member is a puppet and a figure, or a cast mixes the two

conflicting-setting

error

A setting says what is behind the cast twice

duplicate-key

error

A key is written twice in one mapping

duplicate-panel

error

Two panels in a comic script have the same name

figure-staging

error

Staging or a camera for figures a picture draws

font-file

error

A declared font file cannot be read

image-file

error

A supplied picture cannot be read

internal

error

The compiler failed in a way it does not have a rule for

invalid-field

error

A field has the wrong shape or value

layout

error

No layout satisfies the panel’s constraints

missing-field

error

A required field is missing

not-a-mapping

error

The document is not a mapping

off-panel-speaker

error

A line is spoken from off panel by somebody drawn in the panel

ordering-cycle

error

Horizontal ordering contains a cycle

page-layout

error

A page cannot lay out what it says

panel-direction

error

A panel names a reading direction of its own

panel-geometry

error

The panel has no usable area

puppet-file

error

A puppet file a cast member names cannot be read

reflexive-relation

error

A relation relates an actor to itself

sfx-placement

error

A sound effect has no legal position

syntax

error

The document is not valid YAML

unbalanced-emphasis

error

Emphasis opened with an underscore is never closed

unknown-actor

error

Reference to an actor that is not in the cast

unknown-expression

error

Reference to an expression the character does not have

unknown-figure

error

A figure the panel’s picture does not draw

unknown-key

error

Unknown key

unknown-place

error

Reference to a place the library does not have

unknown-pose

error

Reference to a pose the character does not have

unknown-puppet

error

Reference to a character the library does not contain

yaml-anchor

error

A YAML anchor or alias is written

yaml-merge-key

error

A YAML merge key is written

yaml-tag

error

A YAML tag is written

dropped-relation

note

A shared staging relation does not apply in a panel its actor is left out of

looks-like-dialogue

note

A line in a comic script is set like dialogue but is not read as dialogue

panel-count

note

A comic script’s PAGE heading states a count its panels do not match

word-limit

note

A balloon, caption or panel holds more words than a letterer fits well

bold-italic-stand-in

note

No bold italic face is named, so another face stands in for it

camera-retreated

note

The camera stepped back so the cast would fit across the panel

cropped-marks

note

A character’s marks run off the panel at this framing

cropped-mouth

note

A speaking figure’s mouth is cropped out of the panel by the picture’s fit

curved-tail

note

A balloon’s tail bends around a face

inset-covers-face

note

An inset is drawn over a face

italic-stand-in

note

No italic face is named, so the regular face stands in for it

slant-cuts-face

note

A slanted gutter cuts across a face

Errors#

A contradiction the compiler cannot build past. scenet check reports it and fails, and scenet build stops on the first it meets, exit status 1.

artwork-contract#

Level

error

Says

A picture’s artwork contract cannot be read

Keys

Every key of an artwork contract; and cast.<id>.figure, setting.image

Since

0.12

Why it happens. A panel that casts a figure a supplied picture draws reads the picture’s artwork contract, beside it and named after it: art/p01.png has its contract at art/p01.art.yaml. It must be there, and be YAML holding the picture’s size, its figures and its keep_out regions, in the picture’s own pixels. The size must be the picture’s, every point must lie on the picture, and every region must be a simple polygon. A fault inside the contract is reported in it, when the document was checked as a file.

How to fix it. Put the contract beside its picture with the picture’s name, measure it on this picture, and check it against scenet schema --artwork. The debug overlay (scenet build --debug) draws what it declares over the panel.

Checked as artwork-contract.panel.yaml:

# The street has no artwork contract beside it, so nobody can say where its figures are.
cast: {ana: {figure: ana}}
setting: {image: art/street.png}

Open in the playground

scenet check artwork-contract.panel.yaml says:

artwork-contract.panel.yaml:3:18: artwork-contract: artwork contract file 'art/street.art.yaml' was not found beside the document

Fixed:

# The figures picture has its contract beside it, art/figures.art.yaml, measured on it.
cast: {ana: {figure: ana}}
setting: {image: art/figures.png}

Ana, left.

Open in the playground

balloon-placement#

Level

error

Says

A balloon or caption has no legal position

Keys

caption.text, lettering.size, say.text, script

Since

0.3

Why it happens. Every candidate position covered a face, left the panel, overlapped a box already placed, or would have broken reading order.

How to fix it. Widen the panel, shorten the line, or split it across two panels.

Checked as balloon-placement.panel.yaml:

# Valid, but at an extreme close-up the face fills the frame and no word fits.
camera: {shot: extreme_close_up}
panel: {size: [300, 300]}
cast: {alice: {reference: alice}}
script:
  - say: {by: alice, text: "There is no room anywhere in this panel for a line this long."}

Open in the playground

scenet check --deep balloon-placement.panel.yaml says:

balloon-placement.panel.yaml:2:1: balloon-placement: no legal position for balloon 0 spoken by 'alice': every candidate either covered a face, left the panel, overlapped another balloon, lay under an inset, or broke reading order

Fixed:

# A looser shot leaves room around the face for the line.
camera: {shot: medium_shot}
panel: {size: [300, 300]}
cast: {alice: {reference: alice}}
script:
  - say: {by: alice, text: "There is room."}

Medium shot. Alice, centre. Alice: There is room.

Open in the playground

caption-speaker#

Level

error

Says

A caption that is not spoken names a speaker

Keys

caption.by, caption.kind

Since

0.11

Why it happens. by names who says an off-panel line, so only a spoken caption has one. A locale box states a place and a time, a monologue is a voice nobody hears and an editorial one is the writer’s: none of them is said by anybody, so a speaker named on one is a mistake rather than a field to ignore.

How to fix it. Remove by, or make the caption kind: spoken if somebody off panel says it.

Checked as caption-speaker.panel.yaml:

# A locale caption naming a speaker: only a spoken caption has one.
cast: {alice: {reference: alice}}
script:
  - caption: {text: "Midnight. The docks.", kind: locale, by: harbourmaster}

Open in the playground

scenet check caption-speaker.panel.yaml says:

caption-speaker.panel.yaml:4:63: caption-speaker: only a 'spoken' caption may name a speaker, but this one is 'locale'

Fixed:

# A locale caption names nobody; the harbourmaster's words are a spoken caption.
cast: {alice: {reference: alice}}
script:
  - caption: {text: "Midnight. The docks.", kind: locale}
  - caption: {text: "Nobody sails tonight.", kind: spoken, by: harbourmaster}

Medium shot. Alice, centre. Caption: Midnight. The docks. Harbourmaster, off panel: Nobody sails tonight.

Open in the playground

composition#

Level

error

Says

An over: chain cannot be resolved

Keys

over, panels

Since

0.3

Why it happens. A panel inherits from one that does not exist, or the chain is cyclic and so has no fixed point to resolve to.

How to fix it. Check the panel name in over: and that the chain terminates.

Checked as composition.scene.yaml:

# Over a panel that is not there.
cast: {alice: {reference: alice}}
panels:
  one: {}
  two: {over: ghost}

Open in the playground

scenet check composition.scene.yaml says:

composition.scene.yaml:5:15: composition: panel 'two' is over 'ghost', which does not exist; declared panels are ['one', 'two']

Fixed:

# `two` is over `one`, which the scene defines.
cast: {alice: {reference: alice}}
panels:
  one: {}
  two: {over: one}

A strip of 2 panels. Medium shot. Alice, centre. Medium shot. Alice, centre.

Open in the playground

conflicting-cast#

Level

error

Says

A cast member is a puppet and a figure, or a cast mixes the two

Keys

cast, cast.<id>.at, cast.<id>.expression, cast.<id>.facing, cast.<id>.figure, cast.<id>.marks, cast.<id>.pose, cast.<id>.reference

Since

0.12

Why it happens. A cast member is a puppet Scenet poses (reference) or a figure a supplied picture draws (figure), never both. Nobody poses or places a figure, so a puppet’s pose, expression, marks, at and facing do not apply to one. A cast is all puppets or all figures, since staging and the camera would place a puppet over a painted face they cannot see; and one figure is one person, played by one cast member.

How to fix it. Keep reference or figure. On a member inherited from a scene’s defaults, write the other as null, and the same for a puppet’s keys.

Checked as conflicting-cast.panel.yaml:

# A cast member is a puppet Scenet poses or a figure a picture draws, not both.
cast: {ana: {figure: ana, reference: alice}}
setting: {image: art/figures.png}

Open in the playground

scenet check conflicting-cast.panel.yaml says:

conflicting-cast.panel.yaml:2:38: conflicting-cast: cast member 'ana' names a puppet and a figure the picture draws; it is one or the other. Over an inherited member, write `reference: null`

Fixed:

# Ana is the figure the picture draws, and nothing else.
cast: {ana: {figure: ana}}
setting: {image: art/figures.png}

Ana, left.

Open in the playground

conflicting-setting#

Level

error

Says

A setting says what is behind the cast twice

Keys

setting.horizon, setting.image, setting.masses, setting.place

Since

0.6

Why it happens. A place is a mass list – the preset expands into exactly what an author could have written – so naming one and listing the other asks two questions at once, and the compiler will not guess which was meant. A supplied image is a whole backdrop of its own, so it stands alone too: beside a place, masses, or a horizon, which only says where masses meet the ground.

How to fix it. Keep one of the place, the masses and the image. On a panel that inherits one, write it as null to leave it out. What each place expands into is at https://creatoan.github.io/scenet/reference/language/setting.html#settingplace.

Checked as conflicting-setting.panel.yaml:

# A place is a list of masses already, so naming one and listing masses asks twice.
cast: {alice: {reference: alice}}
setting:
  place: shore
  masses: [{kind: sky}]

Open in the playground

scenet check conflicting-setting.panel.yaml says:

conflicting-setting.panel.yaml:4:10: conflicting-setting: 'setting' names a place and lists masses; a place *is* a mass list, so this asks two questions at once. Write one or the other -- https://creatoan.github.io/scenet/reference/language/setting.html#settingplace prints what each place expands into

Fixed:

# The place alone: the shore already has its sky.
cast: {alice: {reference: alice}}
setting:
  place: shore

Medium shot. A shore by day. Alice, centre.

Open in the playground

duplicate-key#

Level

error

Says

A key is written twice in one mapping

Keys

Any key that holds a mapping: camera, caption, cast, lettering, lettering.font, page, panel, panels, say, setting, sfx

Since

0.10

Why it happens. YAML requires every key in a mapping to be unique, but the parser Scenet reads it with builds the document anyway and keeps only the last value – so a panel, a cast member or a pose written twice would lose the first without a word, and the rest would compile. Keys are compared as written, so 1 and 1.0 are two keys, and no and 'no' are one. In a comic script, the same goes for a directive written twice in one panel, and for an @script: directive, which would replace the panel’s cues.

How to fix it. Delete or rename one of the two; the message says which lines they are on.

Checked as duplicate-key.panel.yaml:

# `camera` twice: YAML would keep the second and drop the first without a word.
camera: {shot: close_up}
cast: {alice: {reference: alice}}
camera: {shot: wide}

Open in the playground

scenet check duplicate-key.panel.yaml says:

duplicate-key.panel.yaml:4:1: duplicate-key: key 'camera' appears twice in one mapping, first on line 2 and again on line 4; YAML would keep only the last

Fixed:

# `camera` once, with the shot that was meant.
camera: {shot: wide}
cast: {alice: {reference: alice}}

Long shot. Alice, centre.

Open in the playground

Checked as duplicate-key.script:

---
# `@setting:` twice in one panel: the second would replace the first.
cast: {ALICE: {reference: alice}}
---
PANEL 1
@setting: {weather: rain}
ALICE
Wet again.

@setting: {place: docks}

Open in the playground

scenet check duplicate-key.script says:

duplicate-key.script:10:1: duplicate-key: line 10: '@setting' is written twice in this panel; the first is on line 6. Write it once, with everything it sets

Fixed:

---
# `@setting:` once, with everything it sets.
cast: {ALICE: {reference: alice}}
---
PANEL 1
@setting: {place: docks, weather: rain}
ALICE
Wet again.

A strip of 1 panel. Medium shot. The docks by day, in the rain. ALICE, centre. ALICE: Wet again.

Open in the playground

duplicate-panel#

Level

error

Says

Two panels in a comic script have the same name

Keys

None: it is about the whole document, not about one key

Since

0.10

Why it happens. Panels are named by their PANEL heading, and by their PAGE heading as well when panel numbers start again on each page. Two panels that still share a name – PANEL 1 twice on one page, or twice with no PAGE heading between them – cannot both be kept, and dropping one without a word would lose whatever it held.

How to fix it. Number the panels straight through, or put a PAGE heading before each page whose numbering starts again.

Checked as duplicate-panel.script:

---
# PANEL 1 twice on one page, so the second cannot be told from the first.
cast: {ALICE: {reference: alice}}
---
PAGE 1

PANEL 1
ALICE
Hello.

PANEL 1
ALICE
Hello again.

Open in the playground

scenet check duplicate-panel.script says:

duplicate-panel.script:11:1: duplicate-panel: line 11: PANEL 1 appears twice on page 1; the first is on line 7. Number panels straight through, or start each page with a PAGE heading

Fixed:

---
# The panels are numbered straight through.
cast: {ALICE: {reference: alice}}
---
PAGE 1

PANEL 1
ALICE
Hello.

PANEL 2
ALICE
Hello again.

1 page. Page 1 of 1, 2 panels. Medium shot. ALICE, centre. ALICE: Hello. Medium shot. ALICE, centre. ALICE: Hello again.

Open in the playground

figure-staging#

Level

error

Says

Staging or a camera for figures a picture draws

Keys

camera, staging

Since

0.12

Why it happens. The artist already framed, placed and staged everybody a picture draws, so a staging relation naming a figure has nothing to place, and a camera on a panel whose cast is all figures has nothing to frame: the shot is whatever the picture shows. Either would be a key with no effect, and this language reports slips.

How to fix it. Remove the relation, or the camera. On a panel that inherits a camera, write camera: null.

Checked as figure-staging.panel.yaml:

# The artist framed the picture; a camera has nothing to frame.
camera: {shot: close_up}
cast: {ana: {figure: ana}}
setting: {image: art/figures.png}

Open in the playground

scenet check figure-staging.panel.yaml says:

figure-staging.panel.yaml:2:16: figure-staging: 'camera' frames a cast that a picture draws, and the artist already framed it: the shot is whatever the picture shows. Remove it; on a panel that inherits one, write `camera: null`

Fixed:

# No camera: the shot is whatever the picture shows.
cast: {ana: {figure: ana}}
setting: {image: art/figures.png}

Ana, left.

Open in the playground

font-file#

Level

error

Says

A declared font file cannot be read

Keys

lettering.font, lettering.font.bold_italic, lettering.font.display, lettering.font.italic, lettering.font.regular

Since

0.11

Why it happens. lettering.font names font files, read relative to the folder the document is in. Each must be a relative path, the file must be there, and it must be a TrueType or OpenType font with a Unicode character map, since lettering is measured against it. A document compiled from text with no file behind it has no folder, and so can name no font.

How to fix it. Check the path against the document’s folder, write it relative to that folder, or point it at a .ttf or .otf file.

Checked as font-file.panel.yaml:

# The font is read relative to this document, and there is no such file beside it.
cast: {alice: {reference: alice}}
lettering: {font: fonts/Missing-Regular.ttf}

Open in the playground

scenet check font-file.panel.yaml says:

font-file.panel.yaml:3:19: font-file: font file 'fonts/Missing-Regular.ttf' was not found beside the document

Fixed:

# The font is beside the document, in fonts/.
cast: {alice: {reference: alice}}
lettering: {font: fonts/ComicNeue-Regular.ttf}

Medium shot. Alice, centre.

Open in the playground

image-file#

Level

error

Says

A supplied picture cannot be read

Keys

setting.image

Since

0.12

Why it happens. setting.image names a picture to draw behind the cast, read relative to the folder the document is in. It must be a relative path written with /, the file must be there, and it must be a PNG or JPEG whose header gives its size and whose EXIF does not turn it – renderers disagree on obeying that. A document compiled from text with no file behind it has no folder, and so can name no picture unless the picture is sent with it.

How to fix it. Check the path against the document’s folder, write it relative to that folder, or save the picture as a PNG or JPEG with its pixels upright.

Checked as image-file.panel.yaml:

# The picture is read relative to this document, and there is no such file beside it.
cast: {alice: {reference: alice}}
setting: {image: art/missing.png}

Open in the playground

scenet check image-file.panel.yaml says:

image-file.panel.yaml:3:18: image-file: image file 'art/missing.png' was not found beside the document

Fixed:

# The picture is beside the document, in art/.
cast: {alice: {reference: alice}}
setting: {image: art/street.png}

Medium shot. Alice, centre.

Open in the playground

internal#

Level

error

Says

The compiler failed in a way it does not have a rule for

Keys

None: it is about the whole document, not about one key

Since

0.3

Why it happens. A Scenet error reached the checker without a more specific rule. Worth reporting: either the document found something genuinely new, or a rule is missing from the catalogue.

How to fix it. Please open an issue with the document that produced it.

No document gives it on purpose. It is what a Scenet error with no more specific rule is reported as: a document that finds one has found a gap in this catalogue, or a bug.

invalid-field#

Level

error

Says

A field has the wrong shape or value

Keys

Any key: each of every key holds a value of one shape

Since

0.3

Why it happens. The key is known but what it holds is not what the language accepts there – a string where a number belongs, or a value outside the allowed set.

How to fix it. Check the field’s type and permitted values on its card, from https://creatoan.github.io/scenet/reference/language/keys.html.

Checked as invalid-field.panel.yaml:

# A shot type the language does not have.
camera: {shot: very_close}
cast: {alice: {reference: alice}}

Open in the playground

scenet check invalid-field.panel.yaml says:

invalid-field.panel.yaml:2:16: invalid-field: Input should be 'long_shot', 'wide', 'full_shot', 'medium_full', 'cowboy', 'medium_shot', 'medium_close_up', 'close_up', 'big_close_up' or 'extreme_close_up'

Fixed:

# `close_up` is a shot type the language has.
camera: {shot: close_up}
cast: {alice: {reference: alice}}

Close-up. Alice, centre.

Open in the playground

layout#

Level

error

Says

No layout satisfies the panel’s constraints

Keys

cast, staging

Since

0.3

Why it happens. Nothing is misspelled and nothing is missing, but the panel as described has no solution – most often two actors each required to be left of the other. Panel bounds are deliberately not required, so a merely crowded panel is not this.

How to fix it. Relax or remove a conflicting staging relation.

Checked as layout.panel.yaml:

# Valid, but each actor is in front of the other: no depth order exists.
cast: {alice: {reference: alice}, bob: {reference: bob}}
staging:
  - alice in_front_of bob
  - bob in_front_of alice

Open in the playground

scenet check --deep layout.panel.yaml says:

layout.panel.yaml:2:1: layout: depth ordering is cyclic around 'alice'

Fixed:

# One depth order: Alice in front of Bob.
cast: {alice: {reference: alice}, bob: {reference: bob}}
staging:
  - alice in_front_of bob

Medium shot. Alice, left, in front of Bob; Bob, centre.

Open in the playground

missing-field#

Level

error

Says

A required field is missing

Keys

A required key: caption.text, lettering.font.regular, say.by, say.text, setting.masses[].kind, sfx.text, staging[].object, staging[].predicate, staging[].subject

Since

0.3

Why it happens. The value is required and was not supplied.

How to fix it. Add the field. scenet schema prints the full shape the compiler accepts.

Checked as missing-field.panel.yaml:

# A cast member with no `reference`.
cast:
  alice: {pose: pointing}

Open in the playground

scenet check missing-field.panel.yaml says:

missing-field.panel.yaml:3:10: missing-field: Field required

Fixed:

# Alice names the puppet she is.
cast:
  alice: {reference: alice, pose: pointing}

Medium shot. Alice, left, pointing.

Open in the playground

not-a-mapping#

Level

error

Says

The document is not a mapping

Keys

None: it is about the whole document, not about one key

Since

0.3

Why it happens. A panel document is a mapping of top-level keys – panel, camera, cast, staging, script. A list or a bare scalar cannot be one.

How to fix it. Wrap the content in top-level keys, or check you meant to compile this file.

Checked as not-a-mapping.panel.yaml:

# A list, where a panel is a mapping of top-level keys.
- alice
- bob

Open in the playground

scenet check not-a-mapping.panel.yaml says:

not-a-mapping.panel.yaml:2:1: not-a-mapping: expected a mapping at the top level, found list

Fixed:

# The two of them, as the cast of a panel.
cast:
  alice: {reference: alice}
  bob: {reference: bob}

Medium shot. Alice, left; Bob, centre.

Open in the playground

off-panel-speaker#

Level

error

Says

A line is spoken from off panel by somebody drawn in the panel

Keys

say.by, say.off_panel

Since

0.11

Why it happens. An off-panel speaker is somebody nobody draws: their balloon’s tail ends on the frame, on their side, because there is no mouth in the panel to point at. So they are never in the panel’s cast. A line marked off_panel whose speaker is in the cast contradicts itself, and so does one speaker both on and off panel in the same panel.

How to fix it. Leave the speaker out of this panel’s cast, or drop off_panel.

Checked as off-panel-speaker.panel.yaml:

# Bob is drawn in the panel, so he cannot also speak from outside it.
cast:
  bob: {reference: bob}
script:
  - say: {by: bob, text: "I am right here.", off_panel: true}

Open in the playground

scenet check off-panel-speaker.panel.yaml says:

off-panel-speaker.panel.yaml:5:15: off-panel-speaker: script entry 0 is spoken from off panel by 'bob', who is drawn in this panel; leave them out of the cast, or drop off_panel

Fixed:

# Bob is in the panel, and speaks there.
cast:
  bob: {reference: bob}
script:
  - say: {by: bob, text: "I am right here."}

Medium shot. Bob, centre. Bob: I am right here.

Open in the playground

ordering-cycle#

Level

error

Says

Horizontal ordering contains a cycle

Keys

staging, staging[].predicate

Since

0.3

Why it happens. left_of and right_of are resolved into a linear order before the solver runs, because Cassowary is a linear solver and cannot express the disjunction ‘A left of B or B left of A’. A cycle has no linear order and so no solution.

How to fix it. Remove one of the relations in the cycle; the message names an actor on it.

Checked as ordering-cycle.panel.yaml:

# Each to the left of the other.
cast: {alice: {reference: alice}, bob: {reference: bob}}
staging:
  - alice left_of bob
  - bob left_of alice

Open in the playground

scenet check ordering-cycle.panel.yaml says:

ordering-cycle.panel.yaml:5:5: ordering-cycle: horizontal ordering is cyclic around 'alice'; left_of/right_of relations must form a consistent order

Fixed:

# One order: Alice on the left, Bob on the right.
cast: {alice: {reference: alice}, bob: {reference: bob}}
staging:
  - alice left_of bob

Medium shot. Alice, left; Bob, centre.

Open in the playground

page-layout#

Why it happens. pages: lays the panels of a scene out in tiers. Each placement must name a panel panels: defines, a panel can be on one page once, and the margins and gutters must leave room for every tier and every panel in it. A tier holds panels: or columns:, and two columns that are both stacks may not stand side by side, because readers go across them rather than down. Two insets in one panel must stay a gutter clear of each other. A slant leans the gutters between a tier’s panels, so it needs two panels or more, no columns and no insets, and must leave every panel some width at its top and bottom. A panel bleeds only on a side of its frame that reaches the page’s margin. A document with pages needs panels to lay out.

How to fix it. Check the panel names in pages:, place each panel once, put a panel that spans the tier between two stacks, move or shrink an inset, lean a slant less, bleed only on a side at the page’s edge, or shrink the margin and gutters in page:.

Checked as page-layout.scene.yaml:

# A page placing a panel that does not exist.
cast: {alice: {reference: alice}}
panels: {one: {}}
pages:
  - tiers:
      - panels: [one, ghost]

Open in the playground

scenet check page-layout.scene.yaml says:

page-layout.scene.yaml:6:23: page-layout: page 1 places panel 'ghost', which `panels:` does not define; it has ['one']

Fixed:

# The page places the panel the scene defines.
cast: {alice: {reference: alice}}
panels: {one: {}}
pages:
  - tiers:
      - panels: [one]

1 page. Page 1 of 1, 1 panel. Medium shot. Alice, centre.

Open in the playground

panel-direction#

Level

error

Says

A panel names a reading direction of its own

Keys

direction

Since

0.12

Why it happens. direction says which way the whole comic is read – ltr from the top left, rtl from the top right, as manga are – so it is written once for the document: beside panels: in a scene, in a comic script’s front matter. A page read one way holding a panel read the other has no order a reader could follow, so a panel under panels: that writes direction, even the document’s own, and a script’s @direction:, are refused.

How to fix it. Delete it from the panel, and write direction once for the whole document.

Checked as panel-direction.scene.yaml:

# A panel of a right-to-left scene that would read left to right. The direction is the
# whole document's, written once beside `panels:`.
direction: rtl
cast: {alice: {reference: alice}}
panels:
  first: {}
  second: {direction: ltr}

Open in the playground

scenet check panel-direction.scene.yaml says:

panel-direction.scene.yaml:7:23: panel-direction: 'direction' says which way the whole comic is read, so a panel cannot have one of its own: a page read one way holding a panel read the other has no order a reader could follow. Write it once, beside `panels:`

Fixed:

# The direction is written once, beside `panels:`, and every panel reads that way.
direction: rtl
cast: {alice: {reference: alice}}
panels:
  first: {}
  second: {}

A strip of 2 panels. Medium shot. Alice, centre. Medium shot. Alice, centre.

Open in the playground

panel-geometry#

Level

error

Says

The panel has no usable area

Keys

panel.margin, panel.size

Since

0.3

Why it happens. Panel dimensions must be positive, and the margins must leave something between them. A panel with no interior has nothing to compose in.

How to fix it. Give the panel a positive size, and a margin smaller than half its shorter side.

Checked as panel-geometry.panel.yaml:

# Margins that meet in the middle.
panel: {size: [400, 300], margin: 150}
cast: {alice: {reference: alice}}

Open in the playground

scenet check panel-geometry.panel.yaml says:

panel-geometry.panel.yaml:2:8: panel-geometry: margin leaves no usable panel area

Fixed:

# A margin smaller than half the shorter side.
panel: {size: [400, 300], margin: 20}
cast: {alice: {reference: alice}}

Medium shot. Alice, centre.

Open in the playground

puppet-file#

Level

error

Says

A puppet file a cast member names cannot be read

Keys

Every key of a puppet file; and cast.<id>.reference

Since

0.13

Why it happens. A cast member’s reference that ends in .puppet.yaml names a puppet file, read relative to the folder the document is in, as a font or a picture is. It must be a relative path written with /, the file must be there, and it must be a puppet: YAML that declares its landmarks, joints, parts, anchors and face, each joint it names declared. A document compiled from text with no file behind it has no folder, and so can name no puppet file unless the file is sent with it. A fault inside the file is reported in it, at the key that is wrong, when the document was checked as a file.

How to fix it. Check the path against the document’s folder, write it relative to that folder, or fix the puppet where the finding points and check it against scenet schema --puppet. Writing one is walked through at https://creatoan.github.io/scenet/howto/add_your_own_character.html.

Checked as puppet-file.panel.yaml:

# The puppet is read relative to this document, and there is no such file beside it.
cast: {kid: {reference: puppets/kid.puppet.yaml}}

Open in the playground

scenet check puppet-file.panel.yaml says:

puppet-file.panel.yaml:2:25: puppet-file: puppet file 'puppets/kid.puppet.yaml' was not found beside the document

Fixed:

# The puppet is beside the document, in puppets/.
cast: {kid: {reference: puppets/pip.puppet.yaml}}

Medium shot. Kid, centre.

Open in the playground

reflexive-relation#

Level

error

Says

A relation relates an actor to itself

Keys

staging, staging[].object, staging[].subject

Since

0.3

Why it happens. No predicate in the language means anything reflexively, so an actor placed left of itself is always a typo for a second actor’s id.

How to fix it. Name a different actor as the object of the relation.

Checked as reflexive-relation.panel.yaml:

# An actor placed to the left of itself.
cast: {alice: {reference: alice}}
staging:
  - alice left_of alice

Open in the playground

scenet check reflexive-relation.panel.yaml says:

reflexive-relation.panel.yaml:4:5: reflexive-relation: in staging entry 'alice left_of alice': relation 'left_of' cannot relate 'alice' to itself

Fixed:

# Alice is placed to the left of Bob.
cast: {alice: {reference: alice}, bob: {reference: bob}}
staging:
  - alice left_of bob

Medium shot. Alice, left; Bob, centre.

Open in the playground

sfx-placement#

Level

error

Says

A sound effect has no legal position

Keys

sfx

Since

0.11

Why it happens. A sound effect may cover a figure, and balloons may cover it, but it may never cover a face, leave the panel, lie under an inset or overlap another sound effect. Every candidate position – around its source, around the zone it prefers, and the middle of every zone – did one of those.

How to fix it. Make it smaller or shorter, drop its rotation or arc, or give the panel more room.

Checked as sfx-placement.panel.yaml:

# A large sound effect this long is wider than the whole panel, so no position holds it.
panel: {size: [300, 200]}
cast: {alice: {reference: alice}}
script:
  - sfx: {text: KRAKA-THOOOOOOOOOOOOOOOOOOOOOOOOOM, size: large}

Open in the playground

scenet check --deep sfx-placement.panel.yaml says:

sfx-placement.panel.yaml:2:1: sfx-placement: no legal position for sound effect 0 ('KRAKA-THOOOOOOOOOOOOOOOOOOOOOOOOOM'): every candidate either covered a face, left the panel, lay under an inset or overlapped another sound effect; make it smaller or shorter

Fixed:

# A shorter sound, at its middle size, fits the panel.
panel: {size: [300, 200]}
cast: {alice: {reference: alice}}
script:
  - sfx: {text: KRAK!}

Medium shot. Alice, centre. Sound effect: KRAK!

Open in the playground

syntax#

Level

error

Says

The document is not valid YAML

Keys

None: it is about the whole document, not about one key

Since

0.3

Why it happens. The file could not be parsed at all, so nothing further could be checked. Usually an unclosed bracket or quote, or a line indented inconsistently with the ones around it – and a line that lines up with no line above it is said to be, with how far in the line it likely goes with is. A tab where YAML expects a space – it never accepts one in indentation – is said to be one, and so is a key that is a list or a mapping rather than a name. A comic script’s front matter is YAML too, and is read the same way.

How to fix it. Fix the reported position; YAML errors cascade, so re-check after each fix.

Checked as syntax.panel.yaml:

# A flow sequence that never closes.
cast: {alice: {reference: alice}, bob: {reference: bob}}
staging: [alice left_of bob

Open in the playground

scenet check syntax.panel.yaml says:

syntax.panel.yaml:3:28: syntax: invalid YAML: while parsing a flow sequence
  in "<unicode string>", line 3, column 10:
    staging: [alice left_of bob
             ^
expected ',' or ']', but got '<stream end>'
  in "<unicode string>", line 4, column 1:
    
    ^

Fixed:

# The flow sequence is closed.
cast: {alice: {reference: alice}, bob: {reference: bob}}
staging: [alice left_of bob]

Medium shot. Alice, left; Bob, centre.

Open in the playground

unbalanced-emphasis#

Level

error

Says

Emphasis opened with an underscore is never closed

Keys

caption.text, say.text

Since

0.11

Why it happens. A word written between underscores in dialogue or a caption is stressed, and lettered in bold italic. An underscore that opens a span – nothing alphanumeric before it, something other than a space after it – needs one that closes it. Without one the compiler would have to guess where the stress ends, and setting the rest of the line in bold italic is a confident wrong answer.

How to fix it. Add the closing _ after the last stressed word, or write \_ for an underscore that is not emphasis.

Checked as unbalanced-emphasis.panel.yaml:

# The underscore before `told` opens emphasis and nothing closes it: `_told_` was meant.
cast: {alice: {reference: alice}}
script:
  - say: {by: alice, text: "I _told you so."}

Open in the playground

scenet check unbalanced-emphasis.panel.yaml says:

unbalanced-emphasis.panel.yaml:4:28: unbalanced-emphasis: the emphasis opened by the underscore at character 3 ('_told you so') is never closed; end it with '_' after the last stressed word, or write '\_' for an underscore that is not emphasis

Fixed:

# `_told_`: the stress closes after the word it is on.
cast: {alice: {reference: alice}}
script:
  - say: {by: alice, text: "I _told_ you so."}

Medium shot. Alice, centre. Alice: I told you so.

Open in the playground

unknown-actor#

Level

error

Says

Reference to an actor that is not in the cast

Keys

say.by, sfx.from, staging, staging[].object, staging[].subject

Since

0.3

Why it happens. Every actor id named in staging or script must exist in cast. This is the check no JSON Schema can perform – the value is a perfectly good string, it just does not resolve – and it is among the most common faults in generated documents.

How to fix it. Correct the id, or add the actor to cast. The message lists the cast.

Checked as unknown-actor.panel.yaml:

# `bpb` for `bob`.
cast: {alice: {reference: alice}, bob: {reference: bob}}
script:
  - say: {by: bpb, text: Hello}

Open in the playground

scenet check unknown-actor.panel.yaml says:

unknown-actor.panel.yaml:4:15: unknown-actor: script entry 0 is spoken by unknown actor 'bpb'; cast is ['alice', 'bob']. If they speak from outside the panel, say so with off_panel

Fixed:

# `bob`, who is in the cast.
cast: {alice: {reference: alice}, bob: {reference: bob}}
script:
  - say: {by: bob, text: Hello}

Medium shot. Alice, left; Bob, centre. Bob: Hello.

Open in the playground

unknown-expression#

Level

error

Says

Reference to an expression the character does not have

Keys

cast.<id>.expression

Since

0.6

Why it happens. A cast member’s expression names one its puppet does not declare. The counterpart of unknown-pose: an expression is selected by name exactly as a pose is.

How to fix it. Check the name against the puppet’s declared expressions.

Checked as unknown-expression.panel.yaml:

# Alice's puppet declares no `smug` expression.
cast: {alice: {reference: alice, expression: smug}}

Open in the playground

scenet check unknown-expression.panel.yaml says:

unknown-expression.panel.yaml:2:46: unknown-expression: puppet 'alice' has no expression 'smug'; available: ['angry', 'bored', 'coy', 'happy', 'laughing', 'neutral', 'sad', 'scared', 'shouting', 'surprise']

Fixed:

# `coy`, an expression Alice's puppet declares.
cast: {alice: {reference: alice, expression: coy}}

Medium shot. Alice, centre, coy.

Open in the playground

unknown-figure#

Level

error

Says

A figure the panel’s picture does not draw

Keys

cast.<id>.figure

Since

0.12

Why it happens. A cast member’s figure names a figure in the artwork contract of the panel’s picture. A panel with no picture has nobody for a figure to be. A figure its picture does not declare is simply not in that panel, as a member written (OP) is not; a line spoken by it there, or a sound made by it, is reported, with the figures the picture does draw.

How to fix it. Check the name against the contract’s figures, name the picture with setting.image, or say the line from off panel, leaving the member out of this panel’s cast.

Checked as unknown-figure.panel.yaml:

# A figure is drawn by a picture, and this panel names none to draw it.
cast: {ana: {figure: ana}}

Open in the playground

scenet check unknown-figure.panel.yaml says:

unknown-figure.panel.yaml:2:22: unknown-figure: cast member 'ana' is a figure a picture draws, and this panel names no picture to draw it: name one with `setting.image`, beside its artwork contract

Fixed:

# The panel names the picture that draws Ana.
cast: {ana: {figure: ana}}
setting: {image: art/figures.png}

Ana, left.

Open in the playground

unknown-key#

Level

error

Says

Unknown key

Keys

Any key that holds a mapping: camera, caption, cast, lettering, lettering.font, page, panel, panels, say, setting, sfx; and description

Since

0.3

Why it happens. Validation is strict everywhere: unknown keys are rejected rather than ignored. A misspelled key that was silently dropped would produce a panel that is subtly wrong with no indication of why, which for a language meant to be precise is the worst possible failure.

How to fix it. Check the spelling against every key there is: https://creatoan.github.io/scenet/reference/language/keys.html.

Checked as unknown-key.panel.yaml:

# `cmaera` for `camera`.
cmaera: {shot: close_up}
cast: {alice: {reference: alice}}

Open in the playground

scenet check unknown-key.panel.yaml says:

unknown-key.panel.yaml:2:9: unknown-key: Extra inputs are not permitted

Fixed:

# `camera`, spelled as the language spells it.
camera: {shot: close_up}
cast: {alice: {reference: alice}}

Close-up. Alice, centre.

Open in the playground

unknown-place#

Level

error

Says

Reference to a place the library does not have

Keys

setting.place

Since

0.6

Why it happens. setting.place names a preset that does not exist. The counterpart of unknown-pose: the key is a real field and the value is a perfectly good string, it just does not resolve to a place the compiler can expand.

How to fix it. Check the name against the list of places: https://creatoan.github.io/scenet/reference/language/setting.html#settingplace.

Checked as unknown-place.panel.yaml:

# The library has no place called `moon`.
cast: {alice: {reference: alice}}
setting: {place: moon}

Open in the playground

scenet check unknown-place.panel.yaml says:

unknown-place.panel.yaml:3:18: unknown-place: unknown place 'moon'; known places are alley, desert, docks, field, forest, mountain, office, room, shore, street

Fixed:

# `shore`, a place the library has.
cast: {alice: {reference: alice}}
setting: {place: shore}

Medium shot. A shore by day. Alice, centre.

Open in the playground

unknown-pose#

Level

error

Says

Reference to a pose the character does not have

Keys

cast.<id>.pose

Since

0.6

Why it happens. A cast member’s pose names one its puppet does not declare. The key is spelled correctly – pose is a real field – but the value does not resolve to anything the referenced character can do.

How to fix it. Check the name against the puppet’s declared poses.

Checked as unknown-pose.panel.yaml:

# Alice's puppet declares no `levitating` pose.
cast: {alice: {reference: alice, pose: levitating}}

Open in the playground

scenet check unknown-pose.panel.yaml says:

unknown-pose.panel.yaml:2:40: unknown-pose: puppet 'alice' has no pose 'levitating'; available: ['arms_crossed', 'hands_on_hips', 'pointing', 'standing_neutral']

Fixed:

# `pointing`, a pose Alice's puppet declares.
cast: {alice: {reference: alice, pose: pointing}}

Medium shot. Alice, left, pointing.

Open in the playground

unknown-puppet#

Level

error

Says

Reference to a character the library does not contain

Keys

cast.<id>.reference

Since

0.3

Why it happens. A cast member’s reference names a puppet that is not installed.

How to fix it. Check the name against the shipped library, or name a puppet of your own by its file, relative to the document: reference: puppets/name.puppet.yaml.

Checked as unknown-puppet.panel.yaml:

# A character the library does not have.
cast: {alice: {reference: alicia}}

Open in the playground

scenet check unknown-puppet.panel.yaml says:

unknown-puppet.panel.yaml:2:27: unknown-puppet: unknown character 'alicia'; the library has ['alice', 'bob']

Fixed:

# `alice`, a character the library has.
cast: {alice: {reference: alice}}

Medium shot. Alice, centre.

Open in the playground

yaml-anchor#

Level

error

Says

A YAML anchor or alias is written

Keys

None: it is about the whole document, not about one key

Since

0.14

Why it happens. Scenet YAML has no anchors (&name) or aliases (*name). Reuse is the language’s own – a scene’s defaults, and over: – and an alias expands wherever it is used, without bound: a few lines can stand for a document too big to hold. An unquoted value that starts with *, as Markdown stresses a word, is an alias too.

How to fix it. Write the value out where it is used, or inherit it with over: or a scene’s defaults. For a line that starts with *, quote it, or stress the word with underscores: _told_.

Checked as yaml-anchor.panel.yaml:

# An anchor and an alias, to give bob the look alice has.
camera: {shot: long_shot}
cast:
  alice: &look {reference: alice, pose: pointing}
  bob: *look

Open in the playground

scenet check yaml-anchor.panel.yaml says:

yaml-anchor.panel.yaml:4:10: yaml-anchor: '&look' is a YAML anchor, and Scenet YAML has no anchors or aliases: write the value out where it is used, or inherit it with `over:` or a scene's defaults

Fixed:

# The look written out for each of them.
camera: {shot: long_shot}
cast:
  alice: {reference: alice, pose: pointing, at: left_third}
  bob: {reference: alice, pose: pointing, at: right_third}

Long shot. Alice, left, pointing; Bob, centre, pointing.

Open in the playground

yaml-merge-key#

Level

error

Says

A YAML merge key is written

Keys

None: it is about the whole document, not about one key

Since

0.14

Why it happens. Scenet YAML has no merge key. <<: copied another mapping’s keys into this one in YAML 1.1 and is a key like any other in YAML 1.2, so what it meant depended on which reader read it. A scene’s defaults and over: say what a panel inherits, in the language’s own terms.

How to fix it. Write the keys out, or inherit them with over: or a scene’s defaults.

Checked as yaml-merge-key.panel.yaml:

# A merge key, to copy another camera's keys into this one.
camera: {<<: {shot: wide, angle: low}, shot: medium_shot}
cast: {alice: {reference: alice}}

Open in the playground

scenet check yaml-merge-key.panel.yaml says:

yaml-merge-key.panel.yaml:2:10: yaml-merge-key: '<<' is a YAML merge key, and Scenet YAML has no merge keys: write the keys out, or inherit them with `over:` or a scene's defaults

Fixed:

# The keys written out.
camera: {shot: medium_shot, angle: low}
cast: {alice: {reference: alice}}

Medium shot, from a low angle. Alice, centre.

Open in the playground

yaml-tag#

Level

error

Says

A YAML tag is written

Keys

None: it is about the whole document, not about one key

Since

0.14

Why it happens. Scenet YAML has no tags (!!binary, !!str, !!set, or any !custom): a value means what it says. A tag made a value something it does not look like – !!binary aGVsbG8= lettered hello – and made the reader build whatever type it named, a confusion for an author and an attack surface for a compiler that reads untrusted documents. Where the language expects text, a number or true is the text it looks like anyway, so !!str is never needed.

How to fix it. Delete the tag. To make a value text, quote it.

Checked as yaml-tag.panel.yaml:

# A tag makes the line something it does not look like: `!!binary` lettered `hello`.
cast: {alice: {reference: alice}}
script:
  - say: {by: alice, text: !!binary aGVsbG8=}

Open in the playground

scenet check yaml-tag.panel.yaml says:

yaml-tag.panel.yaml:4:28: yaml-tag: '!!binary' is a YAML tag, and Scenet YAML has no tags: a value means what it says. Delete the tag, and quote the value if it is text

Fixed:

# The line, written as it is lettered.
cast: {alice: {reference: alice}}
script:
  - say: {by: alice, text: hello}

Medium shot. Alice, centre. Alice: hello.

Open in the playground

Notes from scenet check#

A house limit, or something a comic script seems to mean and does not say. The document still compiles, and a note alone never fails the check.

dropped-relation#

Level

note

Says

A shared staging relation does not apply in a panel its actor is left out of

Keys

staging

Since

0.11

In the gallery

A relation left out

Why it happens. A comic script’s ALICE (OP) leaves Alice out of that panel: she is in the scene, not in the frame. cast: {alice: null} leaves her out of a panel that would otherwise inherit her, in YAML or in a script’s @cast:. A relation stated for every panel – ALICE left_of BOB, ALICE looking_at BOB – cannot hold where she is not drawn, so it is left out of that panel. A note, since that changes what the panel stages: Bob is placed, and looks, without her. All but BOB looking_at ALICE while she speaks from off panel there: Bob turns toward her side of the frame, and nothing is noted.

How to fix it. Nothing to do if that is what the panel means; otherwise draw her in it.

Checked as dropped-relation.script:

---
# Alice speaks from off panel, so the relation that places her cannot hold there.
cast:
  ALICE: {reference: alice, at: left_third}
  BOB: {reference: bob, at: right_third}
staging: [ALICE left_of BOB]
---
PANEL 1
ALICE (OP)
Is anybody there?

A strip of 1 panel. Medium shot. BOB, right. ALICE, off panel: Is anybody there?

Open in the playground

scenet check dropped-relation.script says:

dropped-relation.script:9:1: note: dropped-relation: line 9: 'ALICE left_of BOB' does not apply in PANEL 1, where ALICE speaks from off panel and is not drawn

Fixed:

---
# Alice is drawn in the panel, so the relation that places her holds.
cast:
  ALICE: {reference: alice, at: left_third}
  BOB: {reference: bob, at: right_third}
staging: [ALICE left_of BOB]
---
PANEL 1
ALICE
Is anybody there?

A strip of 1 panel. Medium shot. ALICE, left; BOB, right. ALICE: Is anybody there?

Open in the playground

looks-like-dialogue#

Level

note

Says

A line in a comic script is set like dialogue but is not read as dialogue

Keys

None: it is about the whole document, not about one key

Since

0.11

In the gallery

Not read as dialogue

Why it happens. A cue with nothing said under it, or a name in capitals with a line under it where nothing is spoken – before the first PANEL heading, which Dark Horse’s format opens with the writer’s name and address. Read as written, nothing is lost, but a line meant as dialogue would not be lettered, so it is pointed out.

How to fix it. If it is dialogue, put the line under its cue, inside a panel; if not, ignore it.

Checked as looks-like-dialogue.script:

---
# ALICE is set as a cue, but a blank line stands between her and her line.
cast: {ALICE: {reference: alice}}
---
PAGE ONE

Panel 1. A corner, in the rain.

ALICE:

Nobody comes.

1 page. Page 1 of 1, 1 panel. A corner, in the rain. Nobody comes.

Open in the playground

scenet check looks-like-dialogue.script says:

looks-like-dialogue.script:9:1: note: looks-like-dialogue: line 9: ALICE is a cue with nothing said under it: the line after it is blank, or is not a line of dialogue. Write the line under the cue, or delete it

Fixed:

---
# ALICE's line is right under her cue.
cast: {ALICE: {reference: alice}}
---
PAGE ONE

Panel 1. A corner, in the rain.

ALICE:
Nobody comes.

1 page. Page 1 of 1, 1 panel. A corner, in the rain. ALICE: Nobody comes.

Open in the playground

panel-count#

Level

note

Says

A comic script’s PAGE heading states a count its panels do not match

Keys

None: it is about the whole document, not about one key

Since

0.11

In the gallery

A page miscounted

Why it happens. Dark Horse’s script format labels each page with how many panels it has, PAGE ONE (five panels). When the panels under it number something else, a panel heading has often been missed, or written so that it reads as prose – and nothing else would say so. A note, not an error: the panels that are there still compile.

How to fix it. Correct the count, or the panel heading that was not read as one.

Checked as panel-count.script:

---
# The page heading says three panels, and two follow it.
cast: {ALICE: {reference: alice}}
---
PAGE ONE (three panels)

Panel 1. A corner, in the rain.

ALICE:
Where is everybody?

Panel 2. The same corner, empty.

1 page. Page 1 of 1, 2 panels. A corner, in the rain. ALICE: Where is everybody? The same corner, empty.

Open in the playground

scenet check panel-count.script says:

panel-count.script:5:1: note: panel-count: line 5: PAGE ONE says three panels, but 2 panels follow it. A panel heading may have been missed, or read as prose

Fixed:

---
# The page heading says two panels, and two follow it.
cast: {ALICE: {reference: alice}}
---
PAGE ONE (two panels)

Panel 1. A corner, in the rain.

ALICE:
Where is everybody?

Panel 2. The same corner, empty.

1 page. Page 1 of 1, 2 panels. A corner, in the rain. ALICE: Where is everybody? The same corner, empty.

Open in the playground

word-limit#

Level

note

Says

A balloon, caption or panel holds more words than a letterer fits well

Keys

caption.text, say.text, script

Since

0.11

In the gallery

Too many words

Why it happens. Dark Horse’s script format asks for ‘approximately 25 words per balloon, and about 50 words per panel, max’. It is a house limit, not a contradiction: the panel still compiles, so this is a note, and scenet check passes. Words are counted as they are lettered: anything between spaces that holds a letter or a digit, so -- and an ellipsis are not words, and emphasis markers add none. A panel counts its balloons and captions; a sound effect is not counted.

How to fix it. Split the balloon in two, or carry the rest of the words to the next panel.

Checked as word-limit.panel.yaml:

# Twenty-six words in one balloon, one over the twenty-five Dark Horse asks for.
cast:
  bob: {reference: bob}
script:
  - say:
      by: bob
      text: >-
        I have been waiting on this corner since before the rain started, and I am not
        going anywhere until somebody tells me where she really went.

Medium shot. Bob, centre. Bob: I have been waiting on this corner since before the rain started, and I am not going anywhere until somebody tells me where she really went.

Open in the playground

scenet check word-limit.panel.yaml says:

word-limit.panel.yaml:7:13: note: word-limit: this balloon holds 26 words; Dark Horse asks for about 25 a balloon or caption at most

Fixed:

# The same words, split over two balloons.
cast:
  bob: {reference: bob}
script:
  - say:
      by: bob
      text: I have been waiting on this corner since before the rain started.
  - say:
      by: bob
      text: And I am not going anywhere until somebody tells me where she really went.

Medium shot. Bob, centre. Bob: I have been waiting on this corner since before the rain started. Bob: And I am not going anywhere until somebody tells me where she really went.

Open in the playground

Notes from the compiler#

The document is valid, and compiling it decided something it did not literally ask for. scenet build prints each as a note: line, and CompileResult.compile_notes gives each with its name.

bold-italic-stand-in#

Level

note

Says

No bold italic face is named, so another face stands in for it

Keys

lettering.font, lettering.font.bold_italic, say.text

Since

0.11

In the gallery

A face standing in

Why it happens. A stressed word, written between underscores, is lettered in bold italic. When lettering.font names no bold italic face, stressed words are set in its italic face, or its regular one if it names no italic either – so the stress is not seen.

How to fix it. Name the bold italic face, as bold_italic: in lettering.font.

Checked as bold-italic-stand-in.panel.yaml:

# A stressed word is set in bold italic, and lettering.font names no bold italic face.
lettering:
  font:
    regular: fonts/ComicNeue-Regular.ttf
    italic: fonts/ComicNeue-Italic.ttf
cast: {alice: {reference: alice}}
script:
  - say: {by: alice, text: "Is this _really_ italic?"}

Medium shot. Alice, centre. Alice: Is this really italic?

Open in the playground

scenet build bold-italic-stand-in.panel.yaml says:

note: no bold italic face is named in lettering.font, so emphasis is set in Comic Neue Italic; name one as `bold_italic:`

Fixed:

# The bold italic face is named beside the other two.
lettering:
  font:
    regular: fonts/ComicNeue-Regular.ttf
    italic: fonts/ComicNeue-Italic.ttf
    bold_italic: fonts/ComicNeue-BoldItalic.ttf
cast: {alice: {reference: alice}}
script:
  - say: {by: alice, text: "Is this _really_ italic?"}

Medium shot. Alice, centre. Alice: Is this really italic?

Open in the playground

camera-retreated#

Level

note

Says

The camera stepped back so the cast would fit across the panel

Keys

camera.shot, cast, panel.size

Since

0.1

In the gallery

Two characters, Depth and overlap, The camera retreats, A sequence, A comic script, Ten expressions, Insets, A Dark Horse script, A French script, A complete panel

Why it happens. A shot type is a crop landmark and a headroom, in head-heights, so a close-up of one person is a fixed scale. Two people side by side at that scale can be wider than the panel. Rather than crop somebody out, the camera retreats – keeps the shot’s crop line and headroom, at a smaller scale – and the note says by how much, as a share of the framing that was asked for.

How to fix it. Widen the panel, ask for a looser shot, or stage fewer people in it; or accept it, if a slightly looser shot is fine.

Checked as camera-retreated.panel.yaml:

# Two characters side by side, at a close-up, in a panel too narrow for both faces.
panel: {size: [600, 400]}
camera: {shot: close_up}
cast: {alice: {reference: alice}, bob: {reference: bob}}
staging: [alice left_of bob]

Close-up. Alice, left; Bob, right.

Open in the playground

scenet build camera-retreated.panel.yaml says:

note: camera retreated to 94% of the requested 'close_up' framing so the cast would fit across the panel

Fixed:

# A wider panel holds both faces at the close-up that was asked for.
panel: {size: [1200, 400]}
camera: {shot: close_up}
cast: {alice: {reference: alice}, bob: {reference: bob}}
staging: [alice left_of bob]

Close-up. Alice, left; Bob, centre.

Open in the playground

cropped-marks#

Level

note

Says

A character’s marks run off the panel at this framing

Keys

camera.shot, cast.<id>.marks

Since

0.8

In the gallery

Marks cut off

Why it happens. Emanata – plewds, motion lines, a question mark – are drawn outside the head, and the camera frames by the body: it makes no room for them, which is what keeps them from ever moving anybody. A tight shot can therefore crop them, and a mark that vanished without a word would be a surprise.

How to fix it. Ask for a looser shot, or give the marks to somebody they fit around.

Checked as cropped-marks.panel.yaml:

# Bob's plewds are drawn above his head, and a medium shot crops them off the top.
panel: {size: [1000, 700]}
camera: {shot: medium_shot}
cast:
  alice: {reference: alice, at: left_third}
  bob: {reference: bob, pose: arms_crossed, at: right_third, facing: left, marks: [plewds]}
staging:
  - alice left_of bob
  - alice ground_shared_with bob

Medium shot. Alice, left; Bob, right, arms crossed, sweating.

Open in the playground

scenet build cropped-marks.panel.yaml says:

note: bob's plewds run off the panel at this framing; the camera makes no room for marks, so a looser shot shows more

Fixed:

# A long shot leaves room above Bob's head for his plewds.
panel: {size: [1000, 700]}
camera: {shot: long_shot}
cast:
  alice: {reference: alice, at: left_third}
  bob: {reference: bob, pose: arms_crossed, at: right_third, facing: left, marks: [plewds]}
staging:
  - alice left_of bob
  - alice ground_shared_with bob

Long shot. Alice, left; Bob, right, arms crossed, sweating.

Open in the playground

cropped-mouth#

Level

note

Says

A speaking figure’s mouth is cropped out of the panel by the picture’s fit

Keys

setting.fit

Since

0.12

In the gallery

A mouth cropped away

Why it happens. fit: cover fills the panel with a supplied picture and crops what overhangs. When that crops the mouth of a figure who speaks, the balloon’s tail cannot reach it, so it stops on the frame, aimed at where the mouth is.

How to fix it. Write fit: contain, which shows the whole picture, or reshape the panel.

Checked as cropped-mouth.panel.yaml:

# `fit: cover` fills a tall panel with a wide picture and crops Ana, who speaks, away.
panel: {size: [400, 900]}
setting: {image: art/figures.png, fit: cover}
cast:
  ana: {figure: ana}
script:
  - say: {by: ana, text: "Is it always this late?"}

Ana, left. Ana: Is it always this late?

Open in the playground

scenet build cropped-mouth.panel.yaml says:

note: ana's mouth is outside the panel, cropped by the picture's fit, so balloon b0's tail stops on the frame; `fit: contain` shows the whole picture

Fixed:

# `fit: contain` shows the whole picture, Ana's mouth with it.
panel: {size: [400, 900]}
setting: {image: art/figures.png, fit: contain}
cast:
  ana: {figure: ana}
script:
  - say: {by: ana, text: "Is it always this late?"}

Ana, left. Ana: Is it always this late?

Open in the playground

curved-tail#

Level

note

Says

A balloon’s tail bends around a face

Keys

caption.prefer, say.prefer

Since

0.1

In the gallery

A tail that bends

Why it happens. A tail runs from its balloon to the speaker’s mouth, or to the frame for a voice from off panel. When a straight one would cross somebody’s face, it bends around it instead. Nothing is wrong, but a bent tail is usually a sign that the balloon sits far from its speaker, or that the panel is crowded.

How to fix it. Let the balloon sit on its speaker’s side – drop its prefer, or ask for the zone nearer the speaker – or give the panel more room.

Checked as curved-tail.panel.yaml:

# Carol speaks from the left, her balloon asks for the top right, and Bob's head is between.
panel: {size: [900, 600]}
camera: {shot: medium_close_up}
cast:
  bob: {reference: bob, at: center}
script:
  - say: {by: carol, text: "Behind you!", off_panel: left, prefer: top_right}

Medium close-up. Bob, centre. Carol, off panel: Behind you!

Open in the playground

scenet build curved-tail.panel.yaml says:

note: balloon b0 needed a curved tail to clear a face

Fixed:

# The balloon sits on the side the voice comes from, and its tail runs straight.
panel: {size: [900, 600]}
camera: {shot: medium_close_up}
cast:
  bob: {reference: bob, at: center}
script:
  - say: {by: carol, text: "Behind you!", off_panel: left, prefer: top_left}

Medium close-up. Bob, centre. Carol, off panel: Behind you!

Open in the playground

inset-covers-face#

Level

note

Says

An inset is drawn over a face

Keys

insets[].at, insets[].size, panels[].insets

Since

0.10

In the gallery

An inset over a face

Why it happens. An inset is set into a corner of its panel and drawn over it. The panel’s art is staged and framed as if the inset were not there – only its lettering keeps clear – so an inset can cover a face as easily as a patch of sky.

How to fix it. Set the inset into another corner, make it smaller, or frame the panel so that nobody’s face is in that corner.

Checked as inset-covers-face.scene.yaml:

# The clock is set into the top right corner of the street, where Bob's face is.
page: {size: [1500, 1000], margin: 75}
cast:
  alice: {reference: alice, at: left_third}
  bob: {reference: bob, at: right_third, facing: left}
panels:
  street:
    camera: {shot: medium_shot}
    staging: [alice left_of bob]
  clock:
    cast: {alice: null}
    camera: {shot: close_up}
pages:
  - tiers:
      - panels:
          - use: street
            insets:
              - {use: clock, at: top_right, size: 0.35}

1 page. Page 1 of 1, 2 panels. Medium shot. Alice, centre; Bob, centre. Close-up. Bob, centre.

Open in the playground

scenet build inset-covers-face.scene.yaml says:

note: street: an inset covers bob's face; it is drawn over the art, which does not move for it, so put the inset in another corner or reframe the panel

Fixed:

# The clock is set into the bottom left corner, where no face is.
page: {size: [1500, 1000], margin: 75}
cast:
  alice: {reference: alice, at: left_third}
  bob: {reference: bob, at: right_third, facing: left}
panels:
  street:
    camera: {shot: medium_shot}
    staging: [alice left_of bob]
  clock:
    cast: {alice: null}
    camera: {shot: close_up}
pages:
  - tiers:
      - panels:
          - use: street
            insets:
              - {use: clock, at: bottom_left, size: 0.3}

1 page. Page 1 of 1, 2 panels. Medium shot. Alice, centre; Bob, centre. Close-up. Bob, centre.

Open in the playground

italic-stand-in#

Level

note

Says

No italic face is named, so the regular face stands in for it

Keys

caption.kind, caption.text, lettering.font, lettering.font.italic

Since

0.11

In the gallery

A face standing in

Why it happens. Every caption but a spoken one is lettered in italic. lettering.font names the faces a document is lettered in; when it names a regular face and no italic, those captions are set in the regular face. It is the document’s own face that stands in, not the shipped italic: a family mixing two typefaces would not be one family.

How to fix it. Name the italic face beside the regular one, as italic: in lettering.font.

Checked as italic-stand-in.panel.yaml:

# A locale caption is set in italic, and lettering.font names no italic face.
lettering:
  font: {regular: fonts/ComicNeue-Regular.ttf}
cast: {alice: {reference: alice}}
script:
  - caption: {text: "Later, at the type foundry.", kind: locale}

Medium shot. Alice, centre. Caption: Later, at the type foundry.

Open in the playground

scenet build italic-stand-in.panel.yaml says:

note: no italic face is named in lettering.font, so italic captions are set in Comic Neue Regular; name one as `italic:`

Fixed:

# The italic face is named beside the regular one.
lettering:
  font:
    regular: fonts/ComicNeue-Regular.ttf
    italic: fonts/ComicNeue-Italic.ttf
cast: {alice: {reference: alice}}
script:
  - caption: {text: "Later, at the type foundry.", kind: locale}

Medium shot. Alice, centre. Caption: Later, at the type foundry.

Open in the playground

slant-cuts-face#

Level

note

Says

A slanted gutter cuts across a face

Keys

camera.shot, tiers[].slant

Since

0.10

In the gallery

A slant through a face

Why it happens. A slanted tier leans the gutters between its panels. Each panel is staged and framed in its bounding box as usual and then cut to its outline, as a margin would cut it; the camera does not know the cut is there, so it can fall across a face.

How to fix it. Lean the tier less, or frame the shot so the face is clear of the cut: a looser shot, or the face further from the slanted side.

Checked as slant-cuts-face.scene.yaml:

# The tier leans twenty degrees, and its slanted gutter cuts across Bob's close-up face.
page: {size: [1500, 900], margin: 75}
panels:
  swing:
    camera: {shot: full_shot}
    cast: {alice: {reference: alice, facing: right}}
  hit:
    camera: {shot: close_up}
    cast: {bob: {reference: bob, facing: left}}
pages:
  - tiers:
      - {slant: 20, panels: [swing, hit]}

1 page. Page 1 of 1, 2 panels. Full shot. Alice, centre. Close-up. Bob, centre.

Open in the playground

scenet build slant-cuts-face.scene.yaml says:

note: hit: the slanted edge of this panel cuts across bob's face; lean the tier less, or frame the shot so the face is clear of it

Fixed:

# A looser shot of Bob keeps his face clear of the slanted gutter.
page: {size: [1500, 900], margin: 75}
panels:
  swing:
    camera: {shot: full_shot}
    cast: {alice: {reference: alice, facing: right}}
  hit:
    camera: {shot: medium_shot}
    cast: {bob: {reference: bob, facing: left}}
pages:
  - tiers:
      - {slant: 20, panels: [swing, hit]}

1 page. Page 1 of 1, 2 panels. Full shot. Alice, centre. Medium shot. Bob, centre.

Open in the playground