[crisprintsstuff]

First phase of Surface instances (RFC 0022): copy one piece onto the faces, points or one face group of another as live copies that follow the surface.

What's in it

• Placement core (oxy-mesh::instances): anchors (host points and weights) per polygon (quads kept), point or face group; per-copy transforms from the host's current surface: up along the interpolated normal, forward from a world direction (default), the longest edge, the first edge or random; size (share of the face or scene units), lift, turn, random size/turn with a seed; realize for Make real (one face group per copy).
• Renderer: instanced pipelines and entry points (per-instance mat4 at locations 5–8), used only for instanced draws, so plain pieces keep their original shaders. Demo screenshot is pixel-identical to main and shading_timing is unchanged within noise.
• Document and saving: Instancer { source, settings } on the host piece; new skippable INST section (layout in the format.rs header). Sources are saved by their place in the piece list. Older versions skip it and open the host and the hidden source as ordinary pieces.
• Undo: new Step::Instancers and Step::Visible. Adding, changing (a slider drag is one step), removing, and deleting a host (its source is shown again) are each one undo step.
• Editor and UI: a new Instances section in the right panel: pick a piece and Copy onto this piece, then On, Facing, Size, Lift, Turn, Vary size, Vary turn, Seed; Edit source shows the source alone and makes it active, so every tool works on it, and Done editing source puts the scene back; Make real runs as a background job and adds a new piece, keeping the instancer and its source; Remove. Sources show "copied" in the Pieces list. Each source belongs to one instancer, and copies of copies are refused.
• Docs: CHANGELOG, README, ROADMAP, the in-app guide (new "Surface instances" topic), tooltips, and the RFC status.

Performance

Transforms are cached per instancer and worked out again only when the host, the source or the settings change. They are uploaded to the GPU only when they change. From the instance_timing example (release build, 4 cores):

• 10k copies: under 1 ms.
• 100k copies: 5–8 ms.

So sculpting a host with 100k copies adds that much per frame. With no instancers the per-frame cost is iterating the piece list.

Verified

• cargo fmt --check, clippy -D warnings, cargo test --workspace, check_corpus_ip.py.
• New tests:
  • oxy-mesh placement (5)
  • INST round trip, and an older reader skipping it (2)
  • history swap (1)
  • editor: add/undo/redo, one undo step per slider drag, group placement, following a sculpted host and an edited source, Edit source enter/exit, Make real, Remove, deleting a host
• Headless screenshot (lavapipe) of a ball with 920 spikes: copies sit on the surface along the normals, and the Instances section looks right.

Not verified / limitations

• Not run on a real GPU, Windows or macOS.
• Exports (glTF, OBJ, STL, PLY) don't include the copies yet: Make real first (phase 4 adds glTF instancing).
• No scatter, mask or edge placement, tiling, exclusions or fitted copies yet (phases 2–3).
• Copies aren't pickable in the viewport, and the scene bounds (framing, floor) ignore them.
• Make real refuses above 40M triangles instead of asking.
• On triangle meshes, OxyBrush's geometric quad detection pairs some triangles into quads, so a copy can sit on a pair instead of each triangle (the same quads the status bar counts).
• Saving while in Edit source saves the temporary visibility (other pieces hidden); nothing is lost.

---

Generated by Claude Code