Keyform Studio Animation JSON
Generate and validate VASF JSON animations for import into Keyform Studio. Use when asked to create an animation JSON, a "vasf" file, a Keyform Studio animation, or to fix a JSON rejected by the importer.
Generate VASF animation JSON
Produce ONE JSON file describing a 2D animation. The user imports it into Keyform Studio (home ▸ "Import a JSON file" creates a new project; Studio ▸ Shapes ▸ "Import a VASF as instance…" inserts a skeleton into the current project). The importer is strict and reports every problem in French with its path.
references/vasf-example.json is a complete, importable animation that
exercises every feature below — copy its patterns.
Top level
{
"version": 6,
"name": "My animation",
"canvas": {"width": 720, "height": 1280, "fps": 25, "background": "#14161C"},
"theme": {"peau": "#FFE3C2"},
"defs": {"main": {"type": "circle", "width": 56, "height": 56}},
"groups": [{"name": "Head"}],
"shapes": [ ... ],
"skeleton": { ... }
}
| field | default | notes |
|---|---|---|
| version | required | 1–6; use the highest extension you need |
| name | "Animation importée" | project name |
| canvas.width / height | 720 / 1280 | 16…4096 |
| canvas.fps | 25 | 5…60 |
| canvas.background | #14161C | scene background, or "$alias" |
| theme | — | v2 color palette: {"alias": "#RRGGBB"} |
| defs | — | v2 reusable primitive definitions |
| groups | — | v6 element groups |
| shapes | required, ≥ 1 | draw order = array order (first = background) |
| skeleton | — | presence switches the project to skeleton type |
Coordinates: origin top-left, x → right, y → down, positive degrees =
clockwise. Time in seconds, angles in degrees, colors #RRGGBB /
#AARRGGBB.
Shape
{
"name": "Bloc", "type": "rect", "color": "#FF5C5C",
"filled": true, "strokeWidth": 4, "width": 110, "height": 110,
"start": 0, "end": 2, "x": 180, "y": 320,
"rotation": 0, "scale": 1, "opacity": 1,
"keyframes": [ ... ]
}
| field | default | notes |
|---|---|---|
| name | "Forme" | unique; duplicates are auto-renamed "X 2" |
| type | "rect" | rect, circle, line, path, triangle, star, hexagon, cross, heart, arrow |
| color | #5B8DEF | fill/stroke color |
| filled | true | false = outline only |
| strokeWidth | 4 | outline thickness (used when filled=false, always for line) |
| width / height | 110 | primitive size; ignored for path (derived from points) |
| points | — | path only: [x, y] pairs around the shape center, ≥ 2, auto-closed |
| start / end | 0 / latest other end, else 4 | visibility window in seconds; end > start |
| x / y | canvas center | base position of the shape center |
| rotation | 0 | base rotation, degrees |
| scale | 1 | base scale (0.05–4 recommended) |
| scaleX / scaleY | 1 | v2 axis factors — effective scale = scale × factor |
| pivot | [0, 0] | v2 [dx, dy] offset from the shape center, in shape units; rotation and scale turn around it (STATIC) |
| opacity | 1 | 0–1 |
| layers | — | v2 array of primitives (overrides the flat geometry fields) |
| cornerRadius | absent = auto | v5 explicit rectangle radius; 0 = square corners |
| roundTopLeft / roundTopRight / roundBottomRight / roundBottomLeft | true | v5 per-corner switches |
| ref | — | v2 name of a defs entry used as geometry defaults |
| bone | — | whole-shape binding shortcut (same as one bind entry) |
| cycle | — | v2 {"repeat": N} repeats the keyframe pattern |
| keyframes | — | see below |
Shape keyframe
{"t": 0, "x": 180, "y": 320, "rotation": 0, "scale": 1, "opacity": 1,
"strokeWidth": 1, "easing": "easeInOut"}
tseconds ≥ 0, sorted automatically; a keyframe pastendextends it.easing= curve of the segment ARRIVING at this keyframe:linear,easeIn,easeOut,easeInOut(default),step, or a CSS chain"cubic-bezier(x1, y1, x2, y2)".- Any of
x, y, rotation, scale, opacity, strokeWidthmay be omitted and is carried from the previous keyframe (or the base pose). v2 addsscaleX/scaleY.strokeWidthhere animates the stroke factor (visible stroke =strokeWidth× factor). - Keyframes are poses: each property interpolates independently.
Skeleton
{
"name": "Rat",
"bones": [
{"name": "Bras", "joint": [100, 320], "angle": 0, "length": 100},
{"name": "Avant-bras", "parent": "Bras", "joint": [200, 420],
"angle": 90, "length": 80, "z": 0, "ik": false, "bend": 1}
],
"bind": {"Bloc": "Bras"},
"keyframes": [
{"bone": "Bras", "t": 0.5, "angle": -30, "easing": "easeInOut",
"opacity": 0.5, "stretch": 1.2, "squash": 1}
]
}
| field | default | notes |
|---|---|---|
| name | "Squelette" | rig name |
| bones | required, ≥ 1 | parents must be listed before their children |
| bone.name | required | unique |
| bone.joint | required [x, y] | joint position in world canvas coords, at rest |
| bone.angle | 0 | world rest angle, degrees |
| bone.length | 80 | bone length, > 0 |
| bone.parent | none | parent bone NAME |
| bone.z | 0 | draw order of the pieces carried by this bone (−10…10) |
| bone.ik | false | IK chain ROOT: dragging the chain end solves every bone (2 bones = exact solver, more = CCD); the chain follows unique-child bones only |
| bone.bend | 1 | elbow side for 2-bone IK: +1 or −1 |
| bind | — | map shape name → bone name, or "Shape/Layer" → bone |
| cycle | — | v2 {"repeat": N} repeats ALL bone keyframes |
| keyframes | — | bone animation; may instead be embedded in each bone object |
Bone keyframe
{"bone": "Bras", "t": 0.5, "angle": -30, "easing": "easeInOut",
"opacity": 0.5, "stretch": 1.2, "squash": 1, "move": [10, -5]}
boneandtare required.angle= absolute WORLD angle in degrees, NOT a delta. A child whose world rest angle is 90° givenangle: 30rotates −60°.opacity(0–1),stretch(along the bone, 1 = neutral),squash(perpendicular, 1 = neutral) are optional.move=[dx, dy]world translation of the joint from its rest position; children and bound pieces follow rigidly. Combines withangle.- Bone keyframes do NOT carry: an omitted
opacity/stretch/squash/movefalls back to neutral (1/1/1/[0,0]). A keyframe carrying onlyttherefore resets them — always giveangleto animate a bone.
Format versions
Set version to the highest extension you use; a version: 1 file stays valid
and the importer accepts 1 to 6.
- v2 —
layers[]packs several primitives into one shape (local pose per layer,x/yrelative to the shape center;x/y/rotation/scale/opacityandkeyframesremain the GROUP pose).themepalette with"$alias"colors.cycle: {"repeat": N}repeats the keyframe pattern (period = last − first time; end on the starting pose for a clean loop).defs+refdefine geometry once.scaleX/scaleYare axis factors — a keyframe value of 1 REPLACES the factor, it does not restore it.pivotis allowed on the SHAPE only, NEVER insidelayers[](rejected; rotation would fall back to the center). CSS easingcubic-bezier(x1, y1, x2, y2)with x1/x2 in [0,1]; linear identity is (0.333, 0.333, 0.667, 0.667), NOT (0,0,1,1). - v3 — animated color per keyframe:
"color": "#hex"on a single-layer shape,"colors": {"LayerName": "#hex"}on a layered shape (the reverse is rejected). Point morph:"points": [[x,y]…]or"layerPoints": {"LayerName": [[x,y]…]}; the path interpolates point by point, a shorter cloud is padded by repeating its last point, and the reference frame is the BASEpointslist (not each keyframe's bbox, or the morph drifts) — the FIRST keyframe must define the starting cloud (copy the base att: 0). Bonemoveand IK as described above. - v4 —
"flipH": true/"flipV": trueper layer (or at shape level when flat) mirrors the layer CONTENT around its origin; keyframes are untouched. - v5 —
cornerRadiusplus the fourround*switches, flat or insidelayers[]. - v6 — element groups: root
"groups": [{"name": "Head", "color": "#FF8800", "visible": true, "collapsed": false, "x": 0, "y": 0, "rotation": 0, "scaleX": 1, "scaleY": 1}]plus"groupId": "Head"on each member shape.groupIdis the group NAME, resolved after creation, so JSON key order is free; an unknown name is an error. A group holds no keyframes and no bones (its span derives from its children);visible: falsehides all its shapes. Groups are flat: no nesting, one group per shape. The static group transform IS rendered: it wraps each shape's pose and rotates/scales around the group's VISUAL CENTRE (mean of its children's rest positions), not the canvas origin; a neutral group renders exactly like ungrouped shapes. - Bone objects may embed their own
keyframesandcycle(thebonefield is then implied). A bone with its own cycle is excluded from the globalskeleton.cycle, so different bones can run different periods.
Gotchas
- Draw order =
shapesarray order.zIndexis REJECTED on import. - Unknown fields are REJECTED at every level (root, canvas, shape, bone) with the offending path — check spellings.
- Alpha in
#AARRGGBBis REPLACED by the computed opacity, not multiplied. Animateopacityfor fades. - Path inside
layers[]:pointsare recentered on the layer origin — place the path with the layer'sx/y(e.g. a smile:y= vertical center of its bbox). - Layer local pose (
x/y/rotation/scale/opacityinlayers[]) is static: only the group pose, layer COLORS and layer POINTS animate.pivotis not animatable.refworks at shape level only, not insidelayers[]. - No nested project instances.
Workflow
- Design — pick canvas, duration, shapes and timeline. Falling →
easeIn, rising/relaunch →easeOut, hard stop →step, otherwiseeaseInOut. Squash & stretch:scale, or independentscaleX/scaleY(ground impact =scaleX > 1+scaleY < 1). Rotation around an edge →pivoton the shape (e.g. a door:[-width/2, 0]). - Write the JSON to a scratch path with a descriptive name. One root object only.
- Validate —
python3 scripts/validate_vasf.py <file>.json. Fix every error; re-read warnings (auto-rename, scale/axis factors outside 0.05–4, oversized pivot, elastic bezier y, morph starting after t ≈ 0). - Deliver the
.jsonfile itself. If the app rejects it, the "Import impossible" dialog lists the errors with paths — fix and resend.
Animation tips
- Bouncing ball: alternate
easeIn(fall) /easeOut(rise), squash on the ground withscaleover 1–2 keyframes. - Character: shapes at rest, bones at the joints,
bindshape → bone; animate with world-angle bone keyframes (elbow at rest 100° → keyframeangle: 150). - IK: enable
ikon the chain ROOT (shoulder);bendpicks the elbow side on 2-bone chains. - Stay readable: few shapes, short durations (2–8 s), 2–4 keyframes per property.
Related skills
- Downloads
- 357All time
- Security audit
- Pass
- Last updated
- 1mo ago
- Current version
- v1.3.0
- License
- MIT-0
