Shift+click adds a wire to the selection and Ctrl+click toggles it. With two
or more wires selected, X swaps where they come from: two wires trade
sources, more reverse them in target-node and input order, so selecting a
Blend node's foreground and background wires and pressing X swaps the two
layers. The wires stay selected, so X again swaps back. Delete and
Backspace remove every selected wire in one undo step, and the wire menu
gains Swap selected links and Delete selected links.
New commands graph.wire.swap and graph.wire.delete take
{wires: [{to, toPort}, ...]}; a swap that would make a cycle is refused and
changes nothing. Engine and UI tests (real clicks on a Blend node) cover
both; docs/wires-and-alpha.md documents the gestures, the ordering rule and
the commands.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9.7 KiB
Editing wires and viewing alpha in the 3D view
This page documents two editor features: selecting, deleting, swapping and rerouting wires in the graph editor, and the alpha (transparency) support of the 3D view. Both are clean-room implementations; every action is an engine command, so the CLI, the control channel and MCP can do the same as the mouse.
A cut-out material in the 3D view, and a reroute dot pulled out of a wire
Wires in the graph editor
A wire runs from an output port to an input port. Every input takes at most one wire, so a wire is
named by the input it feeds: the target node and its input port (to, toPort).
Gestures
| Gesture | What it does |
|---|---|
| Hover a wire | The wire turns white and the pointer becomes a hand: it can be clicked |
| Click a wire | Selects it alone (drawn thicker, in the accent color); the node selection is cleared |
| Shift+click a wire | Adds it to the wire selection |
| Ctrl+click a wire | Adds it to the wire selection, or removes it when it is already selected |
| Delete or Backspace with wires selected | Deletes every selected wire (one undo step) |
| X with two or more wires selected | Swaps where the selected wires come from (see below); they stay selected, so X again swaps back |
| Drag a wire | Pulls a reroute Dot out of the wire where it was pressed and moves it with the pointer, in one gesture |
| Double-click a wire | Drops a reroute Dot at that point |
| Right-click a wire | Opens the wire menu: Insert reroute dot, Swap selected links (X) (with two or more selected), Delete link / Delete selected links. Right-clicking a wire that is already selected keeps the selection |
| Click anywhere else | Drops the wire selection |
A wire is hit within 5 points of its curve. Node cards, ports and comments sit on top of wires, so a press there acts on them, not on the wire underneath. Alt+drag and middle-drag still pan the canvas.
Swapping wires
Select the wires going into a node and press X to swap their sources. On a Blend node, select the Foreground and Background wires and press X: what fed the foreground now feeds the background and the other way around, so the two layers trade places without rewiring by hand.
- Two wires trade sources.
- More than two reverse their sources. The wires are ordered by target node, then by the order of the inputs on the node (top to bottom), and the first wire's source goes to the last input, the second's to the one before it, and so on. With Foreground, Background and Opacity selected on a Blend, the foreground and opacity sources trade places and the background keeps its own.
- The order you click the wires in does not matter, so the result is predictable.
- Wires into different nodes can be swapped too. A swap that would feed a node into itself (a cycle) is refused with a message, and nothing changes.
- One wire alone cannot be swapped: the editor says to select two or more.
- The swap is one undo step.
Reroute dots
A Dot is the existing dot node: one input, one output, passing its input through unchanged. It
lets a wire bend around other nodes. After a dot is inserted it is selected, so it can be dragged,
deleted (Delete removes it with both of its wires; Backspace, Delete and relink, removes
it and joins the wire back up) or given more dots. Inserting a dot is one undo step: Ctrl+Z
restores the straight wire.
Commands
| Command | Params | Result |
|---|---|---|
graph.wire.insertDot |
{to, toPort, at?: [x, y]} |
Splits the wire feeding to.toPort with a Dot centered at at (graph space; default: midway between the two nodes). Returns {"id": <dot id>} and selects the dot. Errors when no wire feeds that input. |
graph.wire.swap |
{wires: [{to, toPort}, ...]} |
Swaps (two wires) or reverses (more) the sources of the listed wires, as described above. Returns {"swapped": n}. Errors with fewer than two wires, a wire listed twice, a missing wire or a cycle; nothing changes then. |
graph.wire.delete |
{wires: [{to, toPort}, ...]} |
Deletes the listed wires in one undo step (what the Delete key and the menu run). Returns {"deleted": n}. |
graph.disconnect |
{to, toPort} |
Deletes the single wire feeding to.toPort. |
Over the control channel (see control-protocol.md), splitting the wire
feeding node 12's input with a dot at (240, 80), then deleting the wire from the dot to node 12:
{"id": 1, "method": "command.run", "params": {"id": "graph.wire.insertDot", "params": {"to": 12, "toPort": "input", "at": [240, 80]}}}
{"id": 2, "method": "command.run", "params": {"id": "graph.disconnect", "params": {"to": 12, "toPort": "input"}}}
Swapping the two layers of Blend node 7:
{"id": 3, "method": "command.run", "params": {"id": "graph.wire.swap", "params": {"wires": [{"to": 7, "toPort": "foreground"}, {"to": 7, "toPort": "background"}]}}}
session.inspect lists every wire under graph.connections and the dot under graph.nodes
("def": "dot"). The wire selection itself is editor state, like hover, and is not part of the
session.
Alpha in the 3D view
The alpha channel view: white is opaque, black is clear
Where the alpha comes from
- The output with the Opacity usage, read as grayscale, when the graph has one.
- Otherwise the alpha channel of the Base color output, when it is a color image.
- Otherwise the material is opaque.
Transparency
Where the alpha is below one, the surface lets light through: each camera ray composites the
surfaces it meets front to back (color × alpha, the rest passes on) through up to eight layers,
then shows what lies behind: the backdrop, or the environment when Display ▸ Environment
background is on. Back faces seen through a clear front are shaded facing the viewer, so a
cut-out sphere shows its inside. Parallax from the height output applies to every layer.
Display ▸ Transparency (alpha) turns this off, so the alpha is ignored and the mesh is opaque. It is on by default.
Before this change, the opacity output only mixed each pixel with the flat backdrop color; the back of the mesh and the environment never showed through.
Alpha channel view
Display ▸ Show alpha channel, or the checkerboard button in the 3D view's bottom bar, shows the alpha on the mesh unlit: white is opaque, black is clear, values in between are linear (0.5 shows as 50% gray, without tone mapping). The view is labeled Alpha channel in its top-left corner. It shows the first surface only, so the channel reads clearly.
Commands
view.3d takes two booleans; both are part of the session's view3d state and of
session.inspect:
| Param | Default | Meaning |
|---|---|---|
transparency |
true |
See through the mesh where the alpha is below one |
alphaView |
false |
Show the alpha channel instead of the lit material |
{"id": 4, "method": "command.run", "params": {"id": "view.3d", "params": {"alphaView": true}}}
Headless renders (materialcraft-cli render, the render RPC) use the same settings.
Implementation notes
crates/render/src/preview.rs:alpha()picks the alpha source;shade()returns color, alpha and hit distance;trace()composites the layers (MAX_LAYERS = 8, stops once less than 0.1% of the light gets through);Settings::{transparency, alpha_view}.crates/engine/src/wire_cmds.rs:graph.wire.insertDot,graph.wire.swap(unplugs every listed wire first, then reconnects, so a half-swapped state is never mistaken for a cycle) andgraph.wire.delete.crates/ui-egui/src/graph_view.rs: wire hit testing (bezier_points,bezier_at,bezier_distance,wire_at), theWirePressgesture, the multi-wire selection (GraphView::selected_wires), the wire menu,delete_selected_wiresandswap_selected_wires;crates/ui-egui/src/menus.rsgives Delete, Backspace and X to selected wires before the node commands and shortcuts.crates/ui-egui/src/view3d.rs: the Display menu toggles and the bottom-bar button.
Tests
preview::tests::alpha_shows_what_lies_behind_and_the_alpha_view_shows_the_channel: a clear sphere shows the backdrop, transparency off ignores alpha, the opacity output wins over the base color alpha, the alpha view shows exact values.a_wire_splits_with_a_reroute_dot_and_deletes(engine): insertion, wiring, selection, cooking through the dot, single-step undo, the error with no wire, deletion.selected_wires_swap_their_sources_and_delete_together(engine): two-wire swap in any order, three-wire reverse, single-step undo, refused requests (one wire, duplicates, missing wires), a refused cycle that leaves the graph unchanged, deleting several wires in one step.graph_view::tests::clicked_wires_swap_with_x_and_delete_together: real clicks on a Blend node's two wires (the second with Shift), X swaps, X again swaps back, Delete removes both.every_template_is_opaque_in_the_3d_view(engine): no built-in template turns see-through.graph_view::tests::wires_are_hit_near_their_curve_only: wire hit testing.- The
snapshotsUI test renders both screenshots on this page (alpha-transparency,alpha-channel).