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).
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 |
|
|---|---|
|
Half-width of the eyebrow |
|
Radius of the eye |
|
Length of the nose |
|
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.) |
|---|---|---|
|
4 (eyebrows) |
70, 63, 105 / 300, 293, 334 |
|
3 (eyes) |
33, 133, 159, 145 / 263, 362, 386, 374 |
pupil (derived) |
3 (iris) |
468 / 473 |
|
9 (nose) |
1, 2, 98, 327 |
|
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#
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 |
|---|---|
|
Three drops just past the face circle — two off the back of the head, one off the front |
|
Five symbols in an arc over the head |
|
Four symbols in an arc over the head |
|
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, 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 |
|---|---|
|
|
|
|
|
|
|
A polygon: the silhouette lettering pays to cover. Optional |
|
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 |
|---|---|---|
|
A hard exclusion: no box may overlap it, and a tail stops on its edge |
face circle |
|
The tail’s target |
|
|
A cost per area covered, halved for the figure’s own balloon |
hull |
|
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 |
Face feature points |
Face marks; Panel Core |
|
Balloon tail termination |
Face exclusion circle |
Balloon placement (infinite cost) |
Gaze vector |
Balloon placement bias, |
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.