Blocking

"Blocking" is the film term for where the actors stand and which way they face. Instead of positioning each actor by hand, you pick a ready-made formation (a "primitive") and agentwood places everyone — scaled and rotated to fit the spot you chose.

Blocking arranges a group of actors into a named formation with one call. You pass a blocking primitive and the actors to shot.block(primitive, *actors, at=anchor). There are 20 primitives across 2-, 3-, and 4-person groups.

from dsl.blocking import face_to_face, huddle_triangle, two_by_two

shot.block(face_to_face(), bob, anne, at=A1)      # 2
shot.block(huddle_triangle(), a, b, c, at=A1)     # 3
shot.block(two_by_two(), a, b, c, d, at=A1)       # 4

How it works

Each primitive defines a local offset + a yaw per slot. At apply time each slot is transformed:

world_position = anchor_origin + rotate_z(local_offset * actor_scale, anchor_theta)
world_yaw      = anchor_theta + slot_yaw

So actor_scale scales the gaps, the anchor's theta rotates the whole formation, and each slot's own yaw sets which way that actor faces. The actor count must match the slot count.

The primitives

2-person (5)3-person (8)4-person (7)

shoulder_to_shoulder · face_to_face · back_to_back · in_line · conversational_l

face_to_face	shoulder_to_shoulder

lecturer_triangle · leader_in_front · three_single_file · coach_behind · two_lead_one_follow · huddle_triangle · inward_row · attention_right

horizontal_line · four_single_file · two_by_two · diamond_forward · diamond_vip · arrow_wedge · square_inward

two_by_two	square_inward (all face the centre)

Tip

Most primitives accept gap / gap_x / gap_y overrides, e.g. face_to_face(gap=2.0). The default face_to_face gap is 1.5; others default to 1.0–1.25.

Parameter reference

The dials are the gaps — spacing between actors, in subject units (then × actor_scale). Larger = more space.

Group	Dial(s)	Default	Controls
2-person	gap	1.0 (face_to_face 1.5)	distance between the two actors
conversational_l	gap, who_faces	1.0, "left"	spacing + which actor turns in
3-person	gap_x, gap_y	1.0, 1.25	side-to-side / front-to-back spacing
4-person	gap_x, gap_y (square_inward: gap)	1.0, 1.25	grid spacing

shot.block(face_to_face(gap=2.0), a, b, at=A1)            # more space between them
shot.block(two_by_two(gap_x=1.4, gap_y=1.6), a, b, c, d)  # looser grid

Realism levers

A two-hander staged too far apart / mis-faced reads wrong (#15): tighten gap for intimacy, widen for tension. And the anchor's theta rotates the whole formation — orient the group toward the camera or the scene action.

Staging a group for a beat: see Production-Quality Tuning.