Skip to Content
ReferenceMotion APIComposing actions

Composing actions

A person’s performance is a chain of actions, and a scene is several chains performed at once. HumanChain writes those chains. Every action of the vocabulary is a typed method of the chain, so an editor lists the actions and their parameters, and the type checker rejects a misspelt action, a parameter the action does not take and a value outside a closed set.

One person

HumanChain.subject(id) starts a chain. Each method appends one action with that action’s own parameters. act(name, params) appends an action named as data, typed by the name:

import { HumanChain } from "@automovie/motions"; const a = HumanChain.subject("a") .walk({ to: { x: 0, y: 0, z: 4 } }) .act("gesture", { kind: "wave" }) .stand({ seconds: 2 });

AutoMovieMotionHumanActionName from @automovie/interface lists the vocabulary with one line per action, and IAutoMovieMotionHumanActionParams maps each name to its parameters. What an action is directed at is an IAutoMovieMotionTarget: a region of another person, a region of the performer’s own body, a named point of a prop, a point in the world, or none.

HumanChain.subject("a").approach({ target: { kind: "person", subject: "b", region: "sternum" }, at: "personal", });

approach stops at a named distance band, here personal distance, the way the screenplay names it.

The operators

These operators join actions:

ToWrite
Perform one action after anotherchain.sit({ seat }).rise()
Interrupt the last actionchain.walk({ to }).until({ share: 0.5 }).stand()
Do two things at once with one bodychain.walk({ to }).over((u) => u.handToFace({ task: "read" }))
Run two people at oncea.with(b)
Join people in one actionHumanChain.pair(a, b).handshake()
Let another chain align to an actionPass an anchor id as the last argument, chain.punch(params, "jab")
Time an action to another action’s instantb.stand().flinch().sync({ of: "jab", event: "contact" })
Time an action to speech or musica.stand().gesture({ kind: "wave" }).sync({ of: "dialogue", event: "accent", index: 2 })
Cut an action on a cuechain.stand().until({ of: "music", event: "beat", index: 4 })

Cuts

until cuts the last action: at a share of it, at one of its events, at another action’s event, or when a region comes near a target. The action’s own cancel table decides which cuts it allows, and the performance refuses the others.

Overlays

With over, the last action carries the body, and the actions put over it take only the parts they move. A walk keeps the pelvis and the legs and yields its arms, hands and head. Each action’s overlay and yields in HUMAN_ACTIONS say which actions can ride a carrier and what a carrier gives up. Two overlays that need one hand at one time are refused, naming both.

Sync

sync puts one instant of the action, align or its start when absent, on the instant named, and starts the action as early as its body needs for that. Where the performer’s previous action still runs then, it is cut there, which its cancel table must allow. Cut an action with until and put overlays on it with over before syncing it.

Speech and music as cues

Speech and music are cue tracks given to the performance. The screenplay and the score decide their seconds:

import { HumanCue, HumanPerformance } from "@automovie/motions"; new HumanPerformance({ seed, performers, cues: { dialogue: HumanCue.dialogue([{ from: 1, to: 4, accents: [2.0, 3.2] }]), // lineStart, accent, phraseEnd, lineEnd music: HumanCue.beats({ bpm: 96, count: 16 }), // beat, downbeat }, composition, });

Several people

a.with(b) runs two chains side by side. A mutual action defines roles and the action each role performs, and HumanChain.mutual starts those actions together after every cast member’s entry chain:

import { HumanChain, HumanMutual } from "@automovie/motions"; HumanChain.mutual(HumanMutual.handOver, { giver: a, receiver: b }, { prop: "cup", handle: "body" });

The meeting laws in HumanMutual include handshake, highFive and handOver, which solve a shared meeting. HumanChain.pair(a, b) is a shorthand for the handshake and the handover. A production can define its own IAutoMovieMotionHumanMutual over its registered actions.

What the composition can say

The grammar’s axes and operators, read from the installed package:

The axes an action is decided on

NameDecidesCarried by
basewhat carries the bodyIHumanEntryState.supports, HumanObject.seat
travelwhether and how the body goes somewherewalk, run, approach, HumanGait, HumanPursuit
actionwhich action, and which entry of its tableHumanActionName, HUMAN_LEXICON, HumanActionRow
effectorwhich part of the body performs ittouch.With, hand and side parameters
targeta region of a person, a place on an object, a point or noneAutoMovieMotionTarget
objectthe object involved and the contact on itHumanObject, IHumanProp
partnerthe role in an action done togetherIHumanMutual roles
mannereffort, pace, count and holdAutoMovieMotionManner.IManner
layerwhat runs under everything the person doesIHumanLayer, IHumanLayer.IScheduled
timingwhen, against other actions, speech and musicHumanChain.sync, until, HumanCue
seedwhich take of the same compositionHumanPerformance.IInput.seed, HumanVariation

The operators that join actions

NameDecidesCarried by
sequenceone action, then the nextHumanChain methods in order
cutan action ended early inside a window it declaresHumanChain.until
overlaytwo things at once with one bodyHumanChain.over
layersomething added under every actionHumanPerformance.IInput.layers
parallelseveral people at onceHumanChain.with
mutualone action several people do togetherHumanChain.mutual, HumanChain.pair
attachan action on an object's affordanceHumanObject.seat, HumanObject.prop
syncan action timed to another instantHumanChain.sync

When a composition is refused

Building a HumanPerformance throws a HumanRefusal when the vocabulary cannot perform the composition. The refusal names the performer, the action and its occurrence, the axis at fault, the value given, what the axis accepts and one sentence saying what to change:

a.handshake#1 hand: handshake needs the right hand, which holds bottle since pickUp (pickUp); feasible: left; fix: put bottle down or hand it over first, or perform handshake with the free hand

Repair a refusal at the axis it names. Playground shows a refusal on the action it names, with its fix, and Extending the vocabulary covers a beat that no repair realizes.

Last updated on