Asset contract#

What a character must declare for the compiler to place it.

The central rule#

The solver never sees artwork. It sees only a geometric contract. Everything the layout engine needs — how tall the figure is, where its mouth is, which region a balloon must not cover, which way it is looking — is declared as data. Rendering consumes the same contract afterwards.

This is what keeps rendering swappable: the same panel can be emitted as debug wireframes, as vector puppets, or eventually as hand-drawn artwork, with byte-identical layout in every case.

Skeletal puppets#

A character is a skeleton plus parametric limbs, not a picture. A pose is a named set of joint angles, so pointing is data rather than a drawing — which avoids the combinatorial explosion of one image per pose per expression per facing direction.

A complete puppet, cut down to one arm so it fits on a screen. It loads as it stands, and a test keeps it that way; the shipped characters in src/scenet/assets/library/ are the full-size versions. One of your own is a file like it beside the document, which a cast member names by its path — see a puppet of your own and Add your own character, which walks through the gallery’s. Its schema is scenet schema --puppet (editor support associates it with *.puppet.yaml).

sketch.puppet.yaml#
name: sketch
units_per_head: 100

landmarks:          # vertical offsets from head_top -- the crop lines
  head_top: 0
  eyes: 40
  chin: 100
  shoulders: 130
  chest: 200
  waist: 330
  mid_thigh: 470
  knees: 560
  feet: 750         # 7.5 heads, standard adult proportion

joints:             # a tree rooted at root; each offset is from the parent
  root:       {parent: null, offset: [0, 0]}
  spine:      {parent: root, offset: [0, -130]}
  neck:       {parent: spine, offset: [0, -68]}
  head:       {parent: neck, offset: [0, -82]}
  shoulder_l: {parent: neck, offset: [-34, 6]}
  elbow_l:    {parent: shoulder_l, offset: [0, 95]}
  wrist_l:    {parent: elbow_l, offset: [0, 88]}

parts:              # what is drawn: a capsule between two joints, or a blob at one
  - {from: neck, to: root, width: 72}
  - {from: shoulder_l, to: elbow_l, width: 26}
  - {from: elbow_l, to: wrist_l, width: 22}
  - {at: head, radius: 50}

anchors:            # named points the solver addresses -- a tail ends at mouth
  head_top: {joint: head, offset: [0, -50]}
  eyes:     {joint: head, offset: [0, -10]}
  mouth:    {joint: head, offset: [0, 25]}
  feet:     {joint: root, offset: [0, 420]}

face:
  joint: head
  radius: 65                # balloons may never overlap this circle
  features:                 # what is drawn inside it; paired features come in pairs
    brow_l: {offset: [-20, -27], size: 12}
    brow_r: {offset: [20, -27], size: 12}
    eye_l:  {offset: [-20, -12], size: 9}
    eye_r:  {offset: [20, -12], size: 9}
    mouth:  {offset: [0, 25], size: 16}

gaze:
  origin: eyes              # a declared anchor; the direction comes from staging

poses:                      # joint angles, in degrees
  standing_neutral: {elbow_l: -5}
  pointing: {elbow_l: -80, wrist_l: -10}

expressions:
  neutral: {}
  angry: {brow: angled_in, eyes: narrowed, mouth: frown}

A part’s keys say which kind it is: from and to make a bone, at makes a blob. A part is checked only as the kind it is written as, and one that uses the keys of both kinds, or of neither, is a single error saying so.

Faces#

An expression is to features what a pose is to joints: a named record the panel selects by name. A face deforms rather than rotating about bones, which is why an expression is a set of states and not a set of angles — a nose joint would swing a nose.

Feature points#

face.features declares where things are. Each entry is an AnchorSpec-shaped {joint, offset, size}, resolved through exactly the same forward kinematics, mirroring and scaling that anchors get.

They live under face rather than in anchors deliberately. Anchors are how the solver addresses anatomy — a balloon tail terminates at mouth and the solver never learns how a head is drawn. Features are artwork. Putting drawing landmarks into the one namespace that is supposed to be free of them would erode the rule the whole tier exists to enforce.

Feature

size means

brow_l, brow_r

Half-width of the eyebrow

eye_l, eye_r

Radius of the eye

nose

Length of the nose

mouth

Half-width of the mouth

Features are optional, individually — a stylised character genuinely may have no eyebrows — but the paired ones must come in pairs, because a face with one eyebrow is a typo far more often than it is a character.

Pupils are derived, not declared. They are offset inside the eye along the direction of whatever the character is looking_at, so authoring them would mean authoring something the compiler already knows.

The names come from MPEG-4’s groups, not its point set#

The feature names follow the groups of the MPEG-4 FBA facial definition parameters. The standard itself defines 66 displacements over dozens of points, which is a measurement rather than a notation; the grouping is the reusable part, and it lands at about the right size for a drawn face. The mapping below is what buys convertibility later without importing 478 landmarks into the language now:

Scenet feature

MPEG-4 FDP group

MediaPipe Face Mesh landmarks (approx.)

brow_l / brow_r

4 (eyebrows)

70, 63, 105 / 300, 293, 334

eye_l / eye_r

3 (eyes)

33, 133, 159, 145 / 263, 362, 386, 374

pupil (derived)

3 (iris)

468 / 473

nose

9 (nose)

1, 2, 98, 327

mouth

8 (lips)

61, 291, 13, 14

There is no jaw group, which MPEG-4 has. The head is a circle that does not deform, so a jaw would have no geometry to move. Saying so is better than leaving a group silently missing.

The expression vocabulary is a drawing convention#

Part of a puppet file#
expressions:
  neutral:  {}
  happy:    {mouth: smile}
  angry:    {brow: angled_in, eyes: narrowed, mouth: frown}

Each state comes from a closed set — brow from neutral | raised | lowered | angled_in | angled_out, eyes from open | wide | narrowed | half | closed, mouth from neutral | flat | smile | grin | frown | open | small. A state on the wrong feature is an error, not a line quietly ignored.

The ten names the shipped puppets declare are Comic Chat’s emotion wheel plus surprise: neutral, happy, laughing, coy, bored, scared, sad, angry, shouting, surprise.

They are a drawing convention — the small closed set of faces comics actually draw. They are not a claim that a person feeling anger produces this face, and the docs must never make one; see prior art for the literature that rules it out.

Level of detail#

Below a threshold face radius, no features are drawn at all. At a wide framing a head is a couple of dozen panel units across, and five features inside it stop being a face and become a smudge — which is why a cartoonist leaves them out too. scripts/contact_sheet.py renders every expression at every shot type onto one page, which is the only way to decide where that threshold belongs.

Emanata#

Marks drawn around a character — plewds, squeans, grawlixes, briffits; see the language reference. A puppet declares nothing for them. Each is placed from three things every puppet already exposes: the face circle, the facing direction, and the feet landmark. So hand-drawn artwork meets this part of the contract for free.

They are drawn with the same two primitives as a face — sampled strokes and discs — and, like a face, resolved to numbers in Panel Core so the emitter makes no decision. What differs is where they sit: outside the face circle, which is what makes them the solver’s business. Each mark therefore also yields a zone, a padded convex polygon around everything it draws, and the zone is all the solver ever sees of it.

Mark

Placed

plewds

Three drops just past the face circle — two off the back of the head, one off the front

squeans

Five symbols in an arc over the head

grawlixes

Four symbols in an arc over the head

briffits

Puffs on the ground behind the figure, and two trailing strokes

Zones are not in the hull. The hull is what staging spaces characters by and what the camera fits; a character who starts sweating must not stand further from everyone else. Zones are a separate soft cost instead — see design decisions.

Level of detail#

Two thresholds on the face radius. At or above MIN_EMANATA_DETAIL, marks are drawn in full. Below it, each symbol collapses to a filled dot where it would have been — a plewd at long_shot is a dot — except briffit puffs, which are already as simple as a puff of dust gets, and their trailing strokes, which are dropped. Below the face’s own threshold nothing is drawn: a character too small to have a face is too small to be sweating. scripts/contact_sheet.py --marks renders every mark across the shot ladder, which is where the first threshold was set.

Artwork contracts#

A puppet is drawn by Scenet, so everything the solver needs about it comes from its skeleton. A supplied picture may draw its own people, and then the solver needs the same things about them — where each face is, where each mouth is, what each body covers — without looking at the picture any more than it looks at a puppet. An artwork contract declares them, once, beside the picture.

art/p01-street.art.yaml#
# art/p01-street.art.yaml, beside art/p01-street.png
size: [3000, 2000]            # the picture's own size, in pixels
figures:
  ana:
    face: {center: [1240, 610], radius: 150}   # no lettering may cover this disc
    mouth: [1270, 700]                         # where a tail ends
    body: [[1050, 520], [1450, 520], [1500, 2000], [1000, 2000]]   # costly to cover
  ben:
    face: {center: [2210, 580], radius: 140}
keep_out:                     # regions lettering should stay off; a cost, not a rule
  - [[400, 1200], [900, 1200], [900, 1700], [400, 1700]]

It sits beside its picture, named after it. art/p01-street.png has its contract at art/p01-street.art.yaml: the picture’s name with its extension replaced. Nothing in a panel names the contract, so a panel cannot pair a picture with another picture’s measurements, and the two travel together. It is read as the picture is — relative to the document’s folder, or from the files sent with a document — and is read only for a panel whose cast names one of its figures.

Coordinates are the picture’s own pixels, x rightward and y downward from its top left corner, and size says what the contract was measured on. It must be the picture’s size, as its header gives it, exactly: a contract measured on another export of the same picture would put every face somewhere else, so it is refused rather than scaled. Every point lies on the picture, and every region — a body, a keep-out — is a simple polygon of three or more corners.

Key

Meaning

size

[width, height] of the picture it was measured on

figures.<name>.face

{center: [x, y], radius: r}: the disc no balloon, caption or sound effect may cover

figures.<name>.mouth

[x, y]: where the tail of a line it speaks ends — or whatever the sound comes from. Optional: without it a tail aims at the face’s centre

figures.<name>.body

A polygon: the silhouette lettering pays to cover. Optional

keep_out

Polygons lettering should stay off — a sign, a hand, what the panel is about

How each one reaches the solver, and the puppet part it stands in for:

Declared

Treated as

As a puppet’s

face

A hard exclusion: no box may overlap it, and a tail stops on its edge

face circle

mouth

The tail’s target

mouth anchor

body

A cost per area covered, halved for the figure’s own balloon

hull

keep_out

A cost per area covered, at the weight of emanata, never forbidden

emanata zones

Every figure in the contract is in the picture, whether or not a panel casts it: its face is as forbidden as a speaker’s, and its body costs as much, never forgiven since nobody speaks from it. A crowd of five can be declared and two of them cast.

What it does not declare is anything a puppet’s contract has for the solver to choose: no skeleton, no poses, no expressions, no landmarks for the camera to frame by, and no gaze. The artist already framed, posed and staged everyone in the picture. The vocabulary is Manga109’s — a face and a body for each character, with an identity — plus the one thing a letterer needs that Manga109 does not record: the mouth. See prior art.

Its schema is scenet schema --artwork (editor support associates it with *.art.yaml). The geometry goes through the picture’s fit, and Panel Core records it in the panel’s units (Panel Core).

Derived at compile time#

Forward kinematics resolves the skeleton into, per actor:

Output

Used by

World position of every joint

Rendering; Panel Core joints, which the pose export reads

Face feature points

Face marks; Panel Core features, which the pose export reads

mouth anchor

Balloon tail termination

Face exclusion circle

Balloon placement (infinite cost)

Gaze vector

Balloon placement bias, looking_at resolution

Gaze aim

Pupil direction. Computed after placement, since it needs both actors

Face marks

Rendering only. The solver never sees them

Emanata

Rendering

Emanata zones

Balloon and caption placement (soft cost). Never staging, never the camera

Bounding polygon (hull)

Occlusion cost, inter-actor spacing

A figure a picture draws is derived from its artwork contract instead: each point mapped from the picture’s pixels into the panel through the picture’s fit, the same transform that places the picture, so a face lands exactly where the picture draws it under cover and contain alike. Nothing about it is solved for.

Face marks are not in the hull. The head blob already is, and the features sit inside it, so a drawn face pushing balloons further away would be a bug rather than a refinement.

facing mirrors the puppet about its root X axis; anchors and the gaze vector mirror with it.

Landmark requirements#

Every landmark named in the shot table must be present and monotonically increasing from head_top to feet. A puppet missing a landmark cannot be framed with the shot type that crops there, and validation rejects it rather than guessing.