WootBuild.

Studio/docade/Advisory 11

Advisory · advisory-11.md

Advisory 11 — the crane storyboard, and a control your work-list cannot describe

To: docade · From: WootBuild · Date: 2026-08-26 Status: OPEN — supersedes advisory 10's state machine. Nothing delivered. Trigger: writing the crane's storyboard, which is now a required step before any lane that delivers motion is forged.

What changed since advisory 10

Advisory 10 named a state machine by hand. That was one day old and is already withdrawn, because the studio now derives it from the storyboard — clients/docade/storyboard-crane.yaml, five scenes. The scenes are the states and the controls are the inputs, so there is no second list to drift.

crane
  states   entry -> approach -> play -> chute -> reveal

  move    vector2   from `play`    left/right AND back/forth
  drop    trigger   from `play`    releases the claw
  open    trigger   from `reveal`  fired once per tap, repeatedly
  opened  boolean   from `reveal`  set by YOU when the threshold is reached

Two differences from advisory 10 worth catching:

move is a vector2, not a number. Scene 3 moves the claw on two axes — left/right and back/forth. That is a depth axis, and it is the single biggest consequence in this document. See below.

opened is yours, not the file's. The tap threshold is a host decision. The .riv reports taps; it does not decide when enough have landed. Same rule as everywhere else: the client-side artifact makes a claim, the host settles it.

1. Scene 3 needs a joystick, and your work-list has no row for one

"Full frame view of the inside of the crane with a joystick and button. The bottom of the screen controls are fully interactive."

ui-icons has tab-today and tab-prizes. crane has fourteen rows and button is one of them. Nothing anywhere is a joystick.

It is a real, visible, interactive object at the bottom of the most-played screen in the product. It cannot be delivered to a path that does not exist — a filename is a foreign key, which is your rule and we hold it.

What we need: a key and a path, or a decision that the joystick is UI drawn in code rather than art. Either answer is fine and only you can give it. We have not invented a key.

2. Scene 3 is an INTERIOR with depth, and that changes the cabinet

Every version of our crane style so far declares flat front elevation, no perspective — sensible for parts that stack into one machine, and wrong for this scene. Two axes of movement mean the interior needs a floor that recedes and a claw whose scale changes as it travels toward or away from the player.

This is ours to fix and it is recorded, not yours to answer. It is here because it changes what cabinet-frame is: less a facade seen from outside, more a room seen into. If your design intent is a flat 2D machine and the "back and forth" axis is a parallax rather than real depth, say so now — it is the difference between one drawing and another, and we would rather ask than guess.

3. Scenes 1 and 2 are ours, invented, and marked draft

You described the sequence from scene 3. Scenes 1 (entry, the cabinet on Today) and 2 (approach, arriving at the machine) are reconstructions and are flagged draft in the file with their open questions attached. Scene 3's sound is described as "similar to scene two", which is the only evidence scene 2 has.

Overrule freely. Nothing has been drawn for either.

4. Every tap in scene 5 gets its own three responses

"The user does multi-taps, each one with a sound effect, visual, and haptic response."

Recorded as three separate feedback channels on that scene, because each is a different piece of work and only one of them is ours. Per tap, not per threshold — that is what makes the tapping feel like work rather than a loading bar, and it is the kind of detail that disappears if nobody writes it down.

Ours: the visual. Yours: the sound and the haptic. If you want the sound delivered by us that is a capability we do not currently have and would need to acquire — say so and it becomes a decision rather than a surprise.

What we need back

  1. A joystick key and path, or a decision that it is code-drawn UI.
  2. Real depth in scene 3, or flat with parallax? It decides what the cabinet interior is.
  3. Scenes 1 and 2 — confirm, replace, or delete them.
  4. Anything wrong in the state machine above, before it is built into a binary.

Nothing is blocked on 3 or 4. 1 and 2 do block: we will not invent a key, and we will not forge a fourth style version against a sequence that is not settled.