🗂️ Organising a large graph: groups and blackboxes

Past forty blocks, a graph becomes unreadable. Celestory offers two answers, and they have nothing in common.

A group is a coloured frame drawn around your blocks. It changes nothing in your application.

A blackbox is a real cut: it takes blocks out of your graph, moves them into a graph of their own, and lets you call that graph back with a single block. 📦

🎨 Creating a group

Select at least two blocks, then:

• press Cmd/Ctrl + G, or
• right-click the selection → Group selection.

A translucent frame appears, named New group. It hugs the blocks it contains: move a member block and the frame redraws around it.

A group holds only four things: a name, a colour, a lock, and the list of blocks that belong to it. Nothing else. It does not exist at runtime, it slows nothing down, it never plays.

✏️ Renaming and recolouring

Double-click the frame, somewhere there is no block. A small panel opens with two fields: Group name and Group color.

Enter commits the name and closes the panel. Clicking away commits it too. The colour applies as soon as you pick it, transparency included.

🔺 A group does not open and does not fold. It has no inside: what you see is all there is. To get closer to its contents, select it and press F.

➕ Adding and removing blocks

To add a block to an existing group: drag it and drop it onto the frame. It becomes a member.

To remove one: right-click it → Remove from group. If the block belongs to several nested groups, the entry reads Remove from groups and takes it out of all of them at once.

🔺 If the block you removed was the last member, the group disappears with it. An empty group does not exist.

🔒 Locking a group

Click the frame on its own, then right-click → Lock group. A padlock appears in the top-right corner of the frame.

A locked group behaves differently: when you move the frame, the member blocks no longer follow. Handy for a large background area you do not want to disturb every time you click beside a block. Right-click → Unlock group to go back.

🧲 Moving and selecting

Click the frame and drag: every member block moves together. That is the main service a group provides.

To select the blocks without grabbing the frame, hold Shift and drag starting from a point inside the group. The selection rectangle then ignores frames and picks up only blocks and connections.

Groups nest: if every block of one group also belongs to a wider group, the small frame is drawn on top of the large one. Sub-sections work.

🗑️ Deleting a group: your blocks stay

This is the question that worries everyone. The answer is reassuring.

Click the frame on its own (no block selected), then press Delete / Backspace, or right-click → Remove 1 item. Only the frame goes. The blocks, their connections, their values: everything stays exactly where it was, simply ungrouped.

🔺 If your selection also contains blocks — after a Cmd/Ctrl + A, for instance — deleting takes the blocks with it. Check what is selected before you press.

🔺 The other way round: delete every block in a group and the frame erases itself.

📦 The blackbox: cutting for real

Select some blocks, then:

• press Cmd/Ctrl + B, or
• right-click → Blackbox the selection.

Celestory asks for a Blackbox name, then Create a blackbox. The name must be free: if another variable in the project already uses it, the button reads Name already taken and stays disabled.

Here is what happens, all at once:

1. A new graph is created and carries your name.
2. The selected blocks are moved into it — they leave the original graph.
3. Two blocks appear there: Input name on the left and Output name on the right.
4. Every connection that crossed the border of your selection becomes a point on those two blocks.
5. In the space left behind, an Open a graph block is dropped in, already wired to the same neighbours.
6. The editor takes you into the new graph.

The new graph joins the sidebar, inside your module or under Global graphs.

🔁 Calling the same blackbox elsewhere

This is where a blackbox goes beyond a group. The graph you cut out is reusable as many times as you like.

Add an Open a graph block anywhere, and pick your graph in its graph input. The block reconfigures itself at once: it shows the very points carried by the blackbox's Input and Output.

Better still: add a point to the blackbox's Input block, and every Open a graph block that calls it gains that point, across all your graphs. You write a routine once, you call it everywhere.

🔺 Point names are generated automatically when you cut (in, out, text, number…). Rename them from the Input and Output blocks: that is where they come from.

🚧 What a blackbox refuses

🔺 The Start block cannot be blackboxed. If it is part of your selection, nothing happens at all — no message, no alert. Deselect it.

🔺 Neither can a blackbox's Input and Output blocks. They are the border of the graph, so they cannot cross it. Every blackbox graph always keeps its Input block and at least one Output block: you can neither delete them all nor add a second one of the same kind.

🔺 Groups do not travel. If your selection contained frames, they are not recreated in the new graph. The blocks arrive ungrouped and you regroup them by hand.

⚖️ Group or blackbox?

In short: a group tidies what you see, a blackbox tidies what you build. Start with groups. Move to a blackbox the day you copy-paste the same sequence for the third time.

💬 Annotating the canvas

Neither of them replaces a plain sentence sitting next to a tricky area. Celestory has a dedicated block for that: the Comment block, which wires to nothing and only displays your text on the canvas.

Its full reference page lives in the blocks documentation — we are not repeating it here.

The trio that keeps a big project readable: Comment to say why, group to mark where, blackbox to put away what no longer needs to be seen. 🎯

→ Next step: open your largest graph, draw a group around the first sequence you recognise, and name it. Then spot the sequence you have already copied elsewhere: that one deserves a blackbox.

Updated on: 21/09/2026