The shape tool

BlockoutCreate is doc 24's Creation table: shapes with live parameters, the poly shape, and duplicate, mirror and array. ShapeDrag is the two-stage gesture behind it — drag a footprint on the work plane, then drag the height. BlockoutCubeGrid and GridBox are the cube-grid tool, which counts in whole cells. ShapeCommand is a parameter change on the undo stack, SceneClone is the component-wise subtree copy a duplicate is made of, and SceneShapeData is what a .vxscene carries.

Building the level rather than modelling it. The overwhelmingly common block-out edit is *"that corridor should be a metre wider"*, which is one number — so a shape keeps the numbers it was made from and editing one rebuilds it.

You do not want it for a mesh an artist authored. A shape here is generated, and everything about it is arranged so that it can be thrown away and replaced.

A parametric entity has both a mesh and its parameters. The mesh is what draws, picks, selects and gets edited; the parameters are what an inspector shows and what rebuilds the mesh when one changes. That pairing is why entering an element mode on a shape costs it nothing.

⚠ The one-way door is the first edit, not the first mode change. Pressing 4 to look at a shape's faces throws nothing away; extruding one of them does, and MeshEdit.Demote is where the confirmation is asked. It is asked once per session and never again — a dialog on every wall is one people learn to dismiss without reading. What tells them afterwards is SceneDocument.IsPlainMesh, which is the badge and is derived rather than recorded.

⚠ Consecutive parameter changes merge into one history entry. Dragging a width field is one decision made over forty frames, and forty entries for it is the shape of every "undo did not undo what I did" report. A demotion never merges, because it is a different kind of act.

⚠ Sizes are in world units and the transform stays uniform. Nothing here writes a non-uniform scale, which is what keeps a later bevel the same width on every axis and a later projection unstretched.

The gesture, which is world points in and an entity out:

⚠ The entity exists from the moment the footprint does. Drawing a preview and creating something at the end would be two representations of one shape and a preview that can disagree with the result. Cancel undoes back past the create, so Escape leaves nothing behind.

⚠ A completed drag is two history entries, not one, and that is a known papercut. The create is one and the sizing that follows merges into a second, so the first Ctrl+Z after a drag leaves a small box rather than nothing. Folding them would mean holding a transaction open across the frames of a gesture, and CommandStack.Undo refuses inside one — so a Ctrl+Z mid-drag would throw instead of doing nothing. It is stated here rather than left to be discovered.

The cube grid counts in cells, and stays parametric while it does:

⚠ Integers, and that is the point rather than an implementation choice. A box whose extents are cell counts cannot drift off the grid, cannot be a quarter of a cell wide after nine pushes, and lines up with the box beside it exactly. It makes ordinary ShapeKind.Box shapes, so every other verb works on one unchanged.

⚠ Corner mode is where a cube-grid box stops being one. Pulling one corner down a cell makes a ramp or a wedge, which is not a box's three extents — so BlockoutCubeGrid.Corner demotes, and the cell quantisation is what survives.

⚠ A poly shape is a plain mesh from birth. Its parameters would be a polygon of arbitrary length and a height, which is not six numbers — so it would need a record of its own in the scene format and a gesture of its own to edit. What a designer does to one afterwards is move its corners.

⚠ The candidate cell is drawn before it is committed to. BlockoutHover.CubeGrid writes a cell's wire box into SceneLines' overlay channel, and BlockoutMode points SceneViewport.Cursor at it while the pointer is over the work plane — so G builds the cell you are looking at rather than the one at the plane's origin. Its corners go through WorkPlane.ToWorld individually, because a plane set to a wall is rotated and a box drawn from world axes at a rotated plane's centre is not the cell.

BlockoutHover.LoopCut is the same job for the other pointer-driven tool: the loop a cut through the hovered edge's ring would make, computed from the ring and the interpolation MeshOperations.LoopCut itself uses rather than by running it on a copy — a preview that ran the verb would be a second implementation of it, and the day the two disagreed a designer would be shown one cut and given another.

⚠ Mirror copies and never instances. An instance is a link that survives editing, which is a second kind of entity reference and a rule for what happens when one side is edited. A copy is what a block-out pass actually uses, because the two halves stop being symmetrical about ten minutes later.

• Block-out shapes — the generators, and what each parameter means.
• Element selection — the modes and the verbs that edit what this made.
• Face materials — dressing a shape without losing its parameters.
• Editor modes — where the creation verbs are registered and how they claim their keys.