Writing diagrams

Your first drill

Three kinds of line. A drill name, a team with its players, and a beat containing something that happens. Indentation is for your eyes only — the parser ignores it.

S@z1 means "a player called S, standing in zone 1". The name is yours to choose: use S, OH1, Jana, whatever your club says out loud. It has to be unique within its team — it's how the beats below point at that player — but both teams can use the same one, so S on each side is fine.

There are two teams, and they're called red and blue. Every position is worked out from the side of the court its team is on, so those are the only two names that mean a side; anything else is refused rather than drawn in some third colour. A drill on one half only needs red. One other name is accepted, and it isn't a team either — coach, for whoever is feeding the drill from the side.

Choosing a court

A court line picks what gets drawn. Leave it out and you get the full court. It only changes the picture — z4 is z4 whichever court you draw it on, so you can switch at any time without moving anybody.

Saying where

There are three ways to place someone, and you can mix them freely in the same drill. Use whichever is clearest for the thing you're describing.

Zones — the way you already talk

z1 to z6, exactly as a coach names them: front row 4-3-2 left to right, back row 5-6-1. Each team's zones are read from its own side, so red.z1 and blue.z1 are both that team's back-right — which is why they appear on opposite sides of the picture.

Grid — when you need to be exact

g(x, y) in metres, measured from the middle of the net. x runs along the net from -4.5 at the left sideline to +4.5 at the right. y is distance from the net: positive into red's half, negative into blue's. Plain numbers are absolute — g(-3, 6) is the same spot on the floor whichever team you wrote it for, which is exactly what makes it the escape hatch.

Anchors — named lines on the court

baseline, attack-line, net, serve-zone, left-sideline, right-sideline, center, setter-target. Every one of them is read from the acting team's own side, the same way zones are — left-sideline is each coach's own left, so red's and blue's are opposite lines on the picture.

A plus always means in from the line you named — toward the net for baseline and attack-line, toward the middle of the court for the two sidelines. So baseline+3 is three metres in from the baseline and left-sideline+1 is a metre in off the left sideline, and both phrases mean the same thing to either coach instead of flipping sign depending on who you mean. A minus goes the other way, out into the free zone.

setter-target is where the setter takes the ball to distribute it — a metre right of the middle, half a metre off the net, on the seam of zones 3 and 2. It's the one place a coach points at constantly that the 1–6 numbering has no word for, because it isn't a rotational position. It and center name a single spot rather than a line, so unlike the others they take no offset: there's no direction for one number to move a point in. Use g(x, y) for somewhere near them.

You can mix an anchor with a number inside a grid: g(-3, baseline) is three metres left of centre, on the baseline. The anchor has to match the axis it's in — g(baseline, 3) is refused, because a baseline is a distance from the net and can't tell you an x. And an anchor keeps its meaning wherever you write it, so the anchor half stays team-relative while the plain number beside it stays absolute: for a blue player, g(-3, baseline) is blue's baseline.

An offset stops at the net rather than crossing it: baseline+20 puts someone on the net, not in the other half. The far side is the opposition's court, not more of the same instruction.

Naming a place

A place two lines share should have a name instead of two copies of its coordinates. A spots: block declares one as name@place, where the place is a position — any of the three notations above, with a team prefix if it belongs on the other side (deep@blue.baseline+1). Reference it bare, anywhere a place belongs — a target, or a player's own starting spot in the line-up:

W@queue stands a player on the spot exactly as passes to seam sends a ball to one — but only once queue has been declared. The parser reads top to bottom, so a spots: block written below the team that uses it is still an unresolved name — write it first, the same as you would declare a piece of equipment before a beat moves someone to it. An unprefixed spot resolves once, in the first team's own frame, the same rule a teamless bounce already follows — so a one-sided blue drill still puts an anchor-based spot on blue's own half. A spot written with g(x, y) is a plain point on the floor and ignores frame entirely, exactly as it would anywhere else. A position is all a spot may be, though: a prop, a player or another spot is refused, because the spots are laid out before either of those exists to point at.

A teammate is a place

A target doesn't have to be a spot on the floor — it can be a person. "Pass to the setter" is how you'd actually say it, and now you can write it that way: red.A passes to red.B sends the ball wherever B is standing, not to a copy of B's coordinates written out by hand.

That's live, not a snapshot — move B in the line-up, or write a beat where B moves first, and every ball aimed at red.B follows. The team prefix is required, the same as any other target, so write blue.B to aim at the other side's B. A target that reads a moving teammate always uses where they stood as that beat opened, even if the same beat also moves them on somewhere else — so which of two lines you write first never changes what's drawn. A name that isn't on that team's roster is refused and tells you who is, the same message an unplaced actor gets.

Beats

A drill is a sequence of beats, and each beat is one moment. Everything inside a beat happens at once; the next beat happens after. Press play on the court below to watch them in order.

Give a beat a title in quotes and it shows up as you step through — worth doing, because that's what a coach reads when they're running the drill.

Number your own beats starting from 1. beat 0 is not yours to write — it's the line-up, the frame before anything happens, and the viewer draws it for you from where your players start.

What the ball does

Ball actions read as a sentence: who does-what to where. Each verb draws its own kind of line, and in 3D each has its own flight path — a set loops, a spike drives down.

Write blue.z5 to mean the other team's zone 5. Without a prefix the target belongs to whoever is acting, so red.S sets to z4 means red's own zone 4.

The coach

Half of club training starts with the coach putting the ball in play, and the coach is not a player on either side — they don't rotate, they're on nobody's roster, and they have no side of the court to call their own. Declare them the same way a team's line-up is declared, with a coach: block, and address them the same way a player is addressed: coach.C.

tosses is the verb for the feed itself — lobbed up from waist height, arriving wherever the drill needs it played. It reads exactly like any other ball action, and it takes no modifiers of its own; only unplayed applies, the same as it does everywhere.

A coach has no side, so an unprefixed target and the coach's own line-up position both resolve in whichever team the drill declared first — the same rule a bounce, a prop or a spot already follows. tosses isn't reserved for the coach either: any player may use it, the same as any verb. And coach isn't only for feeding — it's a real actor, so it can carry any ball verb at all, such as a coach hitting down balls from a box.

Letting it bounce

Some drills want the ball on the floor — a coach throwing one up to be chased down, or a high ball nobody plays. With nobody behind it, a bounce starts with ball rather than a player, and it names both ends:

ball bounces from center to z6

Both ends are written out because neither can be worked out. Every other ball action starts wherever the player doing it is standing; this bounce has no player, so it needs telling where the ball met the floor and where it is going next.

Once a player sends the ball off the floor themselves — bouncing it through their own legs to a teammate, say — it drops from and reads like any other ball action, because now there is somebody to leave from: red.C bounces to red.D. Nothing marks it as a bounce except the verb itself.

The set above ends with unplayed, and without it the drill does not work. Every verb ends where somebody plays the ball — a set finishes at hitting height because a hitter takes it — so a set nobody touches would stop three metres in the air and the ball would never reach the floor to bounce off it. unplayed says nobody took it, so it lands. It goes on any ball action, and it keeps whatever shape the verb had on the way down.

The dot is where it hits, and the ball swells for an instant as it lands. Looking straight down at a court you cannot see height at all, so on the flat diagram those two marks are the only sign a bounce happened — in 3D you can watch the arc come off the floor. Anything that reaches the ground gets them: the unplayed set landing in beat 1, and an attack where it lands.

It ends where someone plays it, not where it would land again. If you want to show a second bounce, write a second line. And the chase and the dig sit in beats of their own on purpose: a ball action starts from where the player was when the beat opened, so chasing and digging in one beat would draw the dig starting from where they set off.

More than one ball

Every action above already means "the ball" — a drill with no balls: block has exactly one, unnamed, and there is nothing to declare. Reach for balls: once a drill has two moving at once, or needs to say a ball is already in somebody's hands before the first beat opens.

<name> @<place> — the place is anything a target can be, a teammate or a piece of equipment included, so a ball can start already held, or waiting on a cart:

Name which ball a line means the same way you name an actor — a bare word, this time between the verb and to (or right after catches, which has no to). Leave it out and it means whichever ball the actor is holding, which is fine right up until they are holding two: name neither, and the line is refused, listing what they are actually holding rather than guessing which one was meant.

Where a ball ends up

Possession is worked out the same way facing is. Playing a ball takes it out of the actor's hands; it comes to rest in whoever's hands are where it landed, or on the floor if nobody's are — and unplayed always means the floor, however close somebody happens to be standing. Write catches to say so outright, which overrides the worked-out answer rather than merely agreeing with it — a dig that pops loose and gets scooped up a metre from where it actually bounced still reads as caught.

No to, because the ball stops here rather than travelling on. It takes the same ball name any other line does, and unplayed is the one modifier it refuses — a caught ball is, by definition, not one nobody played. A ball nobody's line mentions in a beat stays exactly where it was, carried along if whoever is holding it moves.

Moving people

One verb, moves, and one place: red.S moves to z2. You never write where they set off from, because the drill already says where they are standing — a start you typed in could disagree with the roster, and used to.

A player who moves in one beat is standing at their new place by the next one — you don't have to restate where they are. Two moves by one player in one beat make a path: the second sets off from the end of the first, which is how you walk somebody through a ladder and on to a cone.

Their path is the only thing that adds up inside a beat. Everything else in it happens at once, so a ball they play in that same beat still leaves from where they were standing when it opened — and swapping two lines around changes nothing.

A piece of equipment moves the same way — cart1 moves to g(4, 8). A cone does not run, so the subject is the whole difference.

Facing

Which way somebody is looking is worked out for you — from what they're playing, the ball coming to them, or the way they're walking — so most of the time you never write it. Say so only where the worked-out answer is wrong: a blocker watching the setter instead of the ball, a defender reading the hitter rather than the flight.

red.MB faces red.S — no to, because a facing names its target directly rather than somewhere the ball travels through. It changes no position and takes no note, and it lasts until something changes it, exactly like a position does.

The same suffix works in the line-up, right where a player starts — A@z1 faces z5 — for a drill whose whole point is body position, so it doesn't need a beat 1 made of nothing but faces lines. A written facing beats a worked-out one, whichever form it's written in, and a target can be anything a beat's own target can: a zone, a spot, a prop, or a teammate.

Touching nothing

Most of what happens in a drill is not a touch. Two hands go up at the net while the hitter swings around them, and until now there was no way to draw that — only a beat title that said so and a court with nobody on it. Leave the target off a ball verb and it stops being a touch and becomes something the player did: red.MB blocks, wherever MB already stands.

Any ball verb can be written this way — a bare attacks is an approach jump that swings at nothing — but blocking is the one that comes up constantly, since two blockers going up is the ordinary shape of a drill and neither one touches anything. Modifiers still apply: blocks standing is reaching over the net rather than jumping into it, the same word it means on an attack.

Modifiers

Add a word after the target to change how the ball travels. The two below are the same set to the same place; only the word differs. Switch either court to 3D to see what it actually changes.

standing is the odd one out: every other modifier says where the ball goes, and that one says what the player did. It's registered on two verbs. An attacks is a jump by default — they leave the floor a beat early and hit at the top — and standing is the down ball you hit off your feet, which is how everybody hits in a warm-up. A blocks is a jump too, and standing there is reaching over the net rather than jumping into it, which is most of what a warm-up block actually is. It's the only way to say "don't jump" — for either one.

Setting it behind you

back is the other modifier that describes the player rather than the ball. Where it goes is already in the target — sets to z2 sends it right — so what back adds is that the setter never turned to look at it. Every other contact is played facing the target; a back set is the one that isn't, and staying square to the outside is the whole skill. Watch it in 3D: the setter keeps facing the antenna and the ball comes off the hands behind their head.

A warm-up, in four lines

Pepper needs both of the odd cases at once, which makes it the best thing to look at: standing for the down ball, and a dig played back to the person who dug it. That dig lands exactly where it started, so on the flat court there's no line to draw — the ball just swells and shrinks where it is, because what moved was the height. Switch to 3D and you can watch it go up and come back.

You can also leave yourself a note in quotes at the end of any action line — a ball, a movement, a bounce. It's for the person reading the drill, not the picture, so it never changes what gets drawn.

Equipment

List equipment in an equipment: block before the first beat, then refer to it by name. Anything with a length has an entry and an exit you can run between.

Leave length off a ladder or a line and it still draws real ends, 3m apart — the picture and the diagram never disagree about where they are. Leave orient off and a ladder runs up the court while a line runs along the net, which is how each is drawn most often; write orient=x or orient=y to say otherwise.

orient is x (along the net) or y (up the court). Sizes are metres — leave them out and each type uses a sensible default. The settings belong to the type, so a cone takes a size and not a length: giving it one is refused rather than quietly ignored, because a cone has no ends to run between.

Hoops and tires

Both lie flat on the floor and work as places to land or move through. A hoop is thin and bright; a tire is heavy and dark. Because they're a single spot rather than a run, you point at them by name — there's no entry and exit the way there is on a ladder.

When it complains

Errors name the line they're on, and they never cost you the rest of the drill — every beat that parses still draws, and the diagram still saves. You can walk away half-finished and pick it up later.

One thing that catches people: a blank line ends a team block. A comment line starting with # doesn't, so you can annotate a line-up without breaking it.

Coming from DrillScript 1

The language changed, and nothing rewrote the diagrams you had already saved. A drill written against the old grammar now reports errors instead of drawing — which is deliberate: a silent half-translation would have moved players around without telling you. Every row below is refused by line number, and the message names what replaced it, so you can work down the list the editor gives you.

And five things you can now do that you could not: aim at a teammate (passes to red.B), name a place once and reuse it (spots:), put the coach on the court (coach: and tosses), turn somebody deliberately, in the line-up or a beat (faces), and put more than one ball in play, naming which one a line means and stating outright when it is caught (balls: and catches).

Reference

Releases

You are reading DrillScript 2.1. The language is numbered on its own: a new major number means something that parsed no longer does, or means something else; a new minor number only adds. Every diagram remembers the release it was last saved under, and the editor tells you when yours is older than the language.

Try it in the playground