Add your own character#
A character in Scenet is not a picture. It is a skeleton plus parametric limbs, so a pose is a set of joint angles rather than a drawing — which avoids the combinatorial explosion of one image per pose per expression per facing direction.
That skeleton is declared in a *.puppet.yaml file. Scenet ships two, alice and bob.
This page walks through a third, pip, which the gallery keeps beside its examples, and then
through casting it: in a document, on the command line, in the playground, over MCP and from
Python.
The file#
examples/gallery/puppets/pip.puppet.yaml, in full:
# 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}
Your editor can check a puppet file as you write it, as it checks a panel: the
VS Code extension does for every *.puppet.yaml, and
any editor with a YAML language server does with this on the first line:
# yaml-language-server: $schema=https://creatoan.github.io/scenet/schemas/puppet.schema.json
It completes every key, landmark, face feature and expression state, and flags a key misspelt,
a landmark or standing_neutral missing, or a part that is neither a whole bone nor a whole
blob. scenet schema --puppet prints the same schema. What it cannot see — landmarks out of
order, a joint that does not exist — is the rest of the table below, which scenet check
reports.
Section by section#
units_per_head sets the scale. Everything else is in native units where one head is
100, and the camera converts between those and panel units. Height in head-heights is
derived, not declared:
from pathlib import Path
from scenet import default_library, load_puppet
pip = load_puppet(Path("examples/gallery/puppets/pip.puppet.yaml"))
assert pip.total_height == 500.0
assert pip.heads_tall == 5.0
assert default_library().get("alice").heads_tall == 7.5
landmarks are the crop lines a shot type names, measured downward from the top of the
head. All nine are required — not optional-with-defaults — because any shot type may crop
at any of them, so a puppet missing one is a puppet that cannot be framed at some
perfectly ordinary shot. head_top must be 0, and the rest must increase downward.
joints form a tree, rooted at root, which sits at the landmark root_landmark names —
the waist, unless you say otherwise. A joint’s pose angle rotates the bone arriving at it
and everything below it, which is the formulation that makes posing read naturally:
bending elbow_r swings the upper arm and carries the forearm and hand with it. Positive
angles swing toward screen left, before the figure is mirrored to face the other way.
parts are what gets drawn — a capsule between two joints, or a blob at one, which may
sit off its joint by an offset, as pip’s knot of hair does. They are the only place
appearance enters. The solver sees them only as the outline around them, which staging
spaces characters by and a balloon pays to cover; never as a drawing.
anchors are named attachment points. Two are load-bearing: mouth, where a balloon
tail aims, and eyes, where a gaze starts. head_top and feet are where the figure begins
and ends. Add whatever else you find useful.
face is the disc no balloon may cover. A head is not a circle, but for layout purposes
it is close enough and vastly cheaper — every “would this cover someone’s face?” test
becomes one distance comparison. Its features are what is drawn inside it: brows, eyes, a
nose, a mouth, each riding a joint at an offset, with a size. Declare the ones your character
has, in pairs where they come in pairs. See faces.
poses are named sets of joint angles. Joints you leave out keep their rest angle. A
cast member that names no pose gets standing_neutral, so every puppet must declare one.
expressions are named states of the face’s features — a brow raised, eyes wide, a mouth
open. A cast member that names none gets neutral, so a puppet that declares expressions
must declare that one. The states each feature can take are in the
asset contract.
Cast it in a document#
A cast member names a puppet file by its path, relative to the folder the document is in — exactly as a document names a font or a picture:
cast:
alice: {reference: alice, at: left_third}
pip: {reference: puppets/pip.puppet.yaml, pose: waving, expression: happy}
A reference that ends in
.puppet.yamlis a file; any other is the name of a shipped puppet. A path is never a name, soreference: aliceis always the shipped alice, whatever sits beside the document.The path is read as a font’s is: relative to the document’s folder, wherever
scenetwas run from, with/between folders. An absolute path is refused, so a document and its puppets travel together.puppets/is only a convention;../puppets/pip.puppet.yamlreads a folder of characters several documents share.Only what the cast names is read. A file beside the document that nobody casts changes nothing, and a file several members name is read once.
The pose and expression are the puppet’s own:
pipwaves and throws its arms up, and cannot point, because its file declares nopointing.scenet checklists the ones it does.Panel Core records the reference as written,
puppets/pip.puppet.yaml, and thename:inside the file is what a message calls the puppet.
The gallery’s 69-a-puppet-of-your-own.scene.yaml casts pip beside alice, in every pose and
every expression it has: open it in the playground.
On the command line#
Nothing to add: scenet check and scenet build read the puppet beside the document, as they
read its fonts and pictures, and scenet build --watch rebuilds when it changes.
scenet check examples/gallery/69-a-puppet-of-your-own.scene.yaml
scenet build examples/gallery/69-a-puppet-of-your-own.scene.yaml -o out/
A puppet file is not itself a document: scenet check puppets/pip.puppet.yaml is refused. It is
checked through a document that casts it.
In the playground#
Puppet… adds a .puppet.yaml file to the document’s puppets/ folder for as long as the
tab is open, and says the reference: to write. The gallery’s pip is there already, for any
document to cast.
Over MCP#
Send the file in files, by the path the document writes, as a picture is sent. validate,
compile and render read it from there, and list_puppets given the same files lists it
after the shipped puppets, with its poses and expressions. See the MCP server.
From Python#
A document compiled from text names its puppet the same way, with the file handed over by the path it writes — which is what the playground and the MCP server do:
from scenet import compile_source
from scenet.assets.contract import DEFAULT_LIBRARY_PATH
mine = (DEFAULT_LIBRARY_PATH / "bob.puppet.yaml").read_bytes()
result = compile_source(
"cast: {a: {reference: puppets/mine.puppet.yaml}}",
base={"puppets/mine.puppet.yaml": mine},
)
assert result.core.actors[0].reference == "puppets/mine.puppet.yaml"
A library of your own, looked up by name, still works too — one file at a time, a whole directory, or a mapping built by hand:
from scenet import PuppetLibrary, compile_source, load_puppet
from scenet.assets.contract import DEFAULT_LIBRARY_PATH
alice = load_puppet(DEFAULT_LIBRARY_PATH / "alice.puppet.yaml")
assert alice.name == "alice"
library = PuppetLibrary.from_directory(DEFAULT_LIBRARY_PATH)
assert library.names() == ("alice", "bob")
result = compile_source("cast: {a: {reference: alice}}", library=library)
assert result.core.actors[0].reference == "alice"
from_directory reads every
*.puppet.yaml in a directory, and there the name: inside each file, not its filename, is
what a cast member’s reference matches.
Validation catches the mistakes you will actually make#
Puppet files are validated exhaustively when they are read, because a puppet that is subtly wrong produces a figure that is subtly wrong with nothing to point at:
Mistake |
Caught as |
|---|---|
A landmark missing |
“is missing landmarks […]” |
Landmarks out of order |
“must increase downward from head_top to feet” |
|
“head_top must be 0, it is the origin” |
The root joint not declared |
“is not defined” |
The root joint with a parent |
“must have no parent” |
A joint naming a parent that does not exist |
“names unknown parent” |
A joint cycle |
“sits in a cycle” |
A part, anchor, feature or pose naming a joint that does not exist |
“references unknown joint” |
|
“is not a declared anchor” |
No |
“declares no pose ‘standing_neutral’” |
One of a pair of features without the other |
“is declared without its pair” |
Expressions with no features to move |
“declares expressions but no face features” |
Expressions without |
“declares expressions but not ‘neutral’” |
A part written with the keys of both a bone and a blob, or of neither |
“a part is a bone, … or a blob” |
A key misspelt, or written twice |
“not a key a puppet has here”, “appears twice” |
Two files in one directory declaring the same |
“duplicate puppet name” |
The cycle and orphan checks are not pedantry. Forward kinematics accumulates each joint’s transform from its parent’s, so a cycle would not terminate and an orphan would leave a limb with no defined position.
In a document, each of these is the finding puppet-file, as is a path that is absolute or
names no file. Checked as a file, scenet check reports it in the puppet file, at the key that
is wrong — the file to open to fix it. Checked as text, in the playground or over MCP, it is
reported on the line naming the puppet, with the puppet file’s line in the message.
import pydantic
import pytest
from scenet import PuppetSpec
with pytest.raises(pydantic.ValidationError, match="missing landmarks"):
PuppetSpec.model_validate(
{
"name": "incomplete",
"units_per_head": 100,
"landmarks": {"head_top": 0, "feet": 700},
"joints": {"root": {"parent": None, "offset": [0, 0]}},
"face": {"joint": "root", "radius": 10},
}
)
Make them different from each other#
The two shipped puppets have deliberately different builds — the same 7.5 heads, of a head 4% larger for bob, with broader shoulders and heavier limbs. Pip is five heads tall. That is a testing decision as much as an artistic one: a bug in camera scaling cannot hide behind figures that happen to share a proportion, and neither can a bug in ground-sharing, which aligns feet rather than heads.
If you add characters, make them differ. Identical puppets are a blindfold.
Then stand them together with ground_shared_with, as example 69 does with alice and pip. A
figure in no such group is framed on its own, its head under the top of the panel, so a child
beside an adult would float with its head level with hers; sharing a ground aligns their feet.
What is not modelled#
No hands beyond the end of a capsule, no clothing, no props, and no hair beyond a blob like pip’s knot. A face is a disc with brows, eyes, a nose and a mouth on it, and its expressions are states of those, from a closed vocabulary. The asset contract is the geometric contract — enough for the solver to place things and for the emitter to draw a legible figure. Real artwork would slot in behind the same contract without the solver noticing, which is the reason the boundary is drawn where it is.