Puppet files#
A puppet of your own is a *.puppet.yaml file: a skeleton in its own units, the parts
drawn on it, the landmarks a shot crops at, a face, and the poses and expressions it can take, by
name. A cast member names it by its path, relative to the document, and
the compiler reads only what that cast names. What the solver sees of it, and why, is in the
asset contract; this page has a card for every key.
Every fault in a puppet file is puppet-file: at the key that is wrong, in the puppet file, when the
document naming it is checked as a file, and on the line naming it otherwise. Its schema is
scenet schema --puppet, which an editor associates with *.puppet.yaml; what no schema can say –
landmarks increasing downward, a skeleton that is a tree, every joint a part or a pose names
declared – scenet check does.
A puppet file#
Every card below points here. This is Pip, the gallery’s puppet, five heads tall; the panel after it casts Pip beside Alice.
# Pip: a child, five heads tall, and the gallery's own puppet -- Scenet does not ship it.
#
# A document casts it by its path, relative to the document, as it names a font or a
# picture: `reference: puppets/pip.puppet.yaml`. The `name:` below is what a message calls it.
#
# What sets it apart from alice and bob, who are both seven and a half heads tall:
#
# - Five heads, not seven and a half. A head is the same 100 units as alice's, so the body
# below it is shorter, and the head is big for it -- a child's proportion. At the same
# shot, a camera that framed by fractions of the panel instead of by landmarks in heads
# would get pip visibly wrong.
# - Big eyes, set low in the face, a small nose and a small mouth.
# - A knot of hair on top of the head: a blob, as the head is, so pip reads as pip even at
# a distance, where a face is too small to draw.
#
# Values are native units, one head being 100; landmarks are measured down from the top of
# the head, and each joint's offset from its parent's. The root sits at the waist.
name: pip
units_per_head: 100
root: root
root_landmark: waist
landmarks:
head_top: 0
eyes: 50
chin: 100
shoulders: 120
chest: 165
waist: 245
mid_thigh: 320
knees: 375
feet: 500
joints:
root: {parent: null, offset: [0, 0]}
spine: {parent: root, offset: [0, -80]}
neck: {parent: spine, offset: [0, -45]}
head: {parent: neck, offset: [0, -70]}
shoulder_l: {parent: neck, offset: [-26, 4]}
shoulder_r: {parent: neck, offset: [26, 4]}
elbow_l: {parent: shoulder_l, offset: [0, 62]}
elbow_r: {parent: shoulder_r, offset: [0, 62]}
wrist_l: {parent: elbow_l, offset: [0, 55]}
wrist_r: {parent: elbow_r, offset: [0, 55]}
hip_l: {parent: root, offset: [-20, 8]}
hip_r: {parent: root, offset: [20, 8]}
knee_l: {parent: hip_l, offset: [0, 122]}
knee_r: {parent: hip_r, offset: [0, 122]}
ankle_l: {parent: knee_l, offset: [0, 125]}
ankle_r: {parent: knee_r, offset: [0, 125]}
parts:
- {from: neck, to: root, width: 64}
- {from: shoulder_l, to: elbow_l, width: 22}
- {from: elbow_l, to: wrist_l, width: 18}
- {from: shoulder_r, to: elbow_r, width: 22}
- {from: elbow_r, to: wrist_r, width: 18}
- {from: hip_l, to: knee_l, width: 28}
- {from: knee_l, to: ankle_l, width: 24}
- {from: hip_r, to: knee_r, width: 28}
- {from: knee_r, to: ankle_r, width: 24}
- {at: head, radius: 50}
- {at: head, radius: 16, offset: [0, -56]} # the knot of hair
anchors:
head_top: {joint: head, offset: [0, -50]}
eyes: {joint: head, offset: [0, 0]}
mouth: {joint: head, offset: [0, 26]}
feet: {joint: root, offset: [0, 255]}
face:
joint: head
radius: 60
# Feature points ride the head joint, so they mirror and scale with it. `size` means an
# eye's radius, a brow's or mouth's half-width, a nose's length.
features:
brow_l: {offset: [-19, -22], size: 10}
brow_r: {offset: [19, -22], size: 10}
eye_l: {offset: [-19, -2], size: 12}
eye_r: {offset: [19, -2], size: 12}
nose: {offset: [0, 12], size: 6}
mouth: {offset: [0, 26], size: 12}
gaze:
origin: eyes
poses:
standing_neutral:
elbow_l: -5
elbow_r: 5
waving:
elbow_l: -5
elbow_r: -150
wrist_r: 35
arms_up:
elbow_l: 155
wrist_l: -20
elbow_r: -155
wrist_r: 20
expressions:
neutral: {}
happy: {mouth: smile}
surprise: {brow: raised, eyes: wide, mouth: open}
scared: {brow: angled_out, eyes: wide, mouth: small}
sad: {brow: angled_out, eyes: half, mouth: frown}
camera: {shot: full_shot}
cast:
alice: {reference: alice, at: left_third}
pip: {reference: puppets/pip.puppet.yaml, pose: arms_up, expression: happy, at: right_third, facing: left}
staging: [alice ground_shared_with pip]
name#
The name a cast member’s reference uses.
Where |
A puppet file, a |
Type |
text |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The name the puppet goes by in messages and in Panel Core. A cast member names a puppet file by its path, not by this, so two files may share a name without either shadowing the other or a shipped puppet. See the example.
units_per_head#
How many of the puppet’s own units one head height is.
Where |
A puppet file, a |
Type |
a number |
Values |
above 0 |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The puppet’s own unit, against the one measure every shot is defined in: a head height. Offsets,
widths and radii are in the puppet’s units; landmarks are in heads. A figure is as tall as its
feet landmark says, in heads – Pip is five, Alice seven and a half. See
the example.
landmarks#
Each vertical body landmark, as a distance down from the top of the head, in head units: the crop lines a shot type names.
Where |
A puppet file, a |
Type |
a mapping |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The nine crop lines a shot names, each as a distance down from the top of the head, in heads:
head_top, eyes, chin, shoulders, chest, waist, mid_thigh, knees and feet. All nine
are required, because any shot may crop at any of them, and they must increase downward. What each
shot does with them is in Shot types. See the example.
landmarks.head_top#
The origin every other landmark is measured down from.
Where |
A puppet file, a |
Type |
|
Values |
|
Default |
none: required |
Since |
0.13 |
Diagnostics |
The origin every other landmark is measured down from, so it is 0. See
the example.
joints#
The skeleton, by joint name.
Where |
A puppet file, a |
Type |
a mapping |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The skeleton, by joint name: a tree rooted at root, every joint reaching it through its
parents. A joint’s pose angle rotates the bone arriving at it and everything below it, which is
what makes posing read naturally: bending elbow_l swings the forearm and takes the hand with it.
See the example.
joints.<joint>.parent#
The joint it hangs from. Left out for the root.
Where |
A puppet file, a |
Type |
text |
Default |
none |
Since |
0.13 |
Diagnostics |
The joint this one hangs from. The root has none, and every other joint must reach the root: a cycle, or a joint that hangs from nothing, is refused. See the example.
joints.<joint>.offset#
Where it is from its parent in the rest pose, in the puppet’s own units.
Where |
A puppet file, a |
Type |
|
Default |
|
Since |
0.13 |
Diagnostics |
Where the joint is from its parent in the rest pose, [x, y] in the puppet’s units, with y
downward. See the example.
root#
The joint every other one hangs from.
Where |
A puppet file, a |
Type |
text |
Default |
|
Since |
0.13 |
Diagnostics |
The joint every other one hangs from. It must be declared, with no parent. See the example.
root_landmark#
The landmark the root joint sits at.
Where |
A puppet file, a |
Type |
a name |
Values |
|
Default |
|
Since |
0.13 |
Diagnostics |
The landmark the root joint physically sits at. The skeleton is built outward from the root, while landmarks are measured downward from the top of the head; this is what bridges the two frames. Declared rather than assumed, because a puppet may root itself somewhere other than the waist. See the example.
parts#
The shapes the body is drawn from, back to front.
Where |
A puppet file, a |
Type |
a list of mappings |
Default |
none |
Since |
0.13 |
Diagnostics |
What is drawn, back to front: each part a bone, a capsule between two joints, or a blob, a
disc at one. 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. See the example.
parts[].from#
The joint the bone starts at.
Where |
A puppet file, a |
Type |
text |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The joint a bone starts at. It must be declared. See the example.
parts[].to#
The joint the bone ends at.
Where |
A puppet file, a |
Type |
text |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The joint a bone ends at. It must be declared. See the example.
parts[].width#
How thick it is drawn, in the puppet’s own units.
Where |
A puppet file, a |
Type |
a number |
Values |
above 0 |
Default |
none: required |
Since |
0.13 |
Diagnostics |
How thick a bone is drawn, in the puppet’s units, with round caps at both ends. See the example.
parts[].at#
The joint it is centred on.
Where |
A puppet file, a |
Type |
text |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The joint a blob is centred on – the head, or the chest of a round torso. See the example.
parts[].radius#
Its radius, in the puppet’s own units.
Where |
A puppet file, a |
Type |
a number |
Values |
above 0 |
Default |
none: required |
Since |
0.13 |
Diagnostics |
A blob’s radius, in the puppet’s units. See the example.
parts[].offset#
Where its centre is from that joint, in the puppet’s own units.
Where |
A puppet file, a |
Type |
|
Default |
|
Since |
0.13 |
Diagnostics |
Where a blob’s centre is from its joint, before posing. See the example.
anchors#
Named attachment points, such as mouth and eyes, each on a joint.
Where |
A puppet file, a |
Type |
a mapping |
Default |
none |
Since |
0.13 |
Diagnostics |
Named points that ride along with a joint. They are how the solver addresses anatomy without
knowing anatomy: a balloon’s tail ends at mouth, and the line of sight starts at the
gaze origin, conventionally eyes. See the example.
anchors.<anchor>.joint#
The joint it rides along with.
Where |
A puppet file, a |
Type |
text |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The joint the anchor rides along with, through every pose. It must be declared. See the example.
anchors.<anchor>.offset#
Where it is from that joint, in the puppet’s own units, before posing.
Where |
A puppet file, a |
Type |
|
Default |
|
Since |
0.13 |
Diagnostics |
Where the anchor is from its joint, before posing. See the example.
face#
Where the face is, and what is drawn in it.
Where |
A puppet file, a |
Type |
a mapping |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The disc no balloon, caption or sound effect may cover, and what is drawn inside it. A circle rather than a polygon: faces are roughly round, the test is cheap, and a slightly generous face only puts a balloon a little further away, which is never wrong. What a face is drawn from is in the asset contract. See the example.
face.joint#
The joint the face is centred on: the head, unless the puppet says otherwise.
Where |
A puppet file, a |
Type |
text |
Default |
|
Since |
0.13 |
Diagnostics |
The joint the face is centred on. See the example.
face.offset#
Where the face’s centre is from that joint, in the puppet’s own units.
Where |
A puppet file, a |
Type |
|
Default |
|
Since |
0.13 |
Diagnostics |
Where the face’s centre is from its joint, before posing. See the example.
face.radius#
The face’s radius, in the puppet’s own units: the circle no balloon covers.
Where |
A puppet file, a |
Type |
a number |
Values |
above 0 |
Default |
none: required |
Since |
0.13 |
Diagnostics |
The face’s radius, in the puppet’s units: the circle lettering may not overlap. See the example.
face.features#
What is drawn inside the face, by feature. Empty for a plain round head.
Where |
A puppet file, a |
Type |
a mapping |
Default |
none |
Since |
0.13 |
Diagnostics |
What is drawn inside the face, by feature: brow_l, brow_r, eye_l, eye_r, nose and
mouth, named after MPEG-4’s facial feature groups. Each is optional – a stylised character may
have no eyebrows – but a pair comes in pairs, since a face with one eyebrow is a typo far more often
than it is a character. Pupils are not declared: they are placed inside each eye toward whoever the
character is looking at. A puppet with no features is drawn as it was before faces existed, a
filled circle, and may declare no expressions. See the example.
face.features.<feature>.joint#
The joint the feature rides, practically always head.
Where |
A puppet file, a |
Type |
text |
Default |
|
Since |
0.13 |
Diagnostics |
The joint the feature rides, which is the head for practically every face. See the example.
face.features.<feature>.offset#
Where the feature is from that joint, in the puppet’s own units, before posing.
Where |
A puppet file, a |
Type |
|
Default |
|
Since |
0.13 |
Diagnostics |
Where the feature is from its joint, before posing, mirrored with the puppet. See the example.
face.features.<feature>.size#
How big the feature is drawn, in the puppet’s own units: an eye’s radius, a brow’s or a mouth’s half-width, a nose’s length.
Where |
A puppet file, a |
Type |
a number |
Values |
0 or more |
Default |
|
Since |
0.13 |
Diagnostics |
What the number means depends on the feature: an eye’s radius, a brow’s or a mouth’s half-width, a nose’s length. Zero draws the feature as a bare point. See the example.
gaze#
Where the puppet’s line of sight starts.
Where |
A puppet file, a |
Type |
a mapping |
Default |
each key’s own |
Since |
0.13 |
Diagnostics |
Where the puppet’s line of sight starts. Its direction is not declared: it comes from staging, so a
looking_at relation is enough and nobody computes an angle. See the example.
gaze.origin#
The anchor the line of sight starts at, conventionally eyes. It must be declared.
Where |
A puppet file, a |
Type |
text |
Default |
|
Since |
0.13 |
Diagnostics |
The anchor the line of sight starts at, which must be one of the puppet’s anchors. See the example.
poses#
Named poses, each a set of joint angles.
Where |
A puppet file, a |
Type |
a mapping |
Default |
none: required |
Since |
0.13 |
Diagnostics |
Named poses, each a mapping of joint to angle, in degrees, that a cast member selects with
pose. A joint a pose leaves out keeps its rest angle. standing_neutral is
required of every puppet, since it is what a member gets when it names no pose, and every joint a
pose names must be declared. See the example.
expressions#
Named expressions, each a state of brow, eyes and mouth.
Where |
A puppet file, a |
Type |
a mapping |
Default |
none |
Since |
0.13 |
Diagnostics |
Named expressions, each a state of the brows, the eyes and the mouth, that a cast member selects
with expression. An expression is to features what a pose is to
joints, but a face deforms rather than rotating about bones, which is why it is a set of states and
not of angles. A puppet that declares any declares neutral, which a member gets unasked, and has
face features for them to move. See the example.
expressions.<expression>.brow#
The brows’ state.
Where |
A puppet file, a |
Type |
a name |
Values |
|
Default |
|
Since |
0.13 |
Diagnostics |
What the eyebrows are doing. angled_in puts the inner ends down, the anger brow; angled_out puts
them up, the sad or frightened one. Inner and outer are taken against the face’s centre rather than
the page, so both survive mirroring. See the example.
expressions.<expression>.eyes#
The eyes’ state.
Where |
A puppet file, a |
Type |
a name |
Values |
|
Default |
|
Since |
0.13 |
Diagnostics |
How open the eyes are. half is the heavy-lidded eye of boredom, distinct from narrowed, the
squint of anger or suspicion: one droops, the other is tightened. See the example.
expressions.<expression>.mouth#
The mouth’s state.
Where |
A puppet file, a |
Type |
a name |
Values |
|
Default |
|
Since |
0.13 |
Diagnostics |
What the mouth is doing. grin is an open smile, smile a closed one, and small the reticent
little mouth that does most of the work in a coy face. See the example.