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:
- A new graph is created and carries your name.
- The selected blocks are moved into it — they leave the original graph.
- Two blocks appear there: Input name on the left and Output name on the right.
- Every connection that crossed the border of your selection becomes a point on those two blocks.
- In the space left behind, an Open a graph block is dropped in, already wired to the same neighbours.
- 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?
| Group | Blackbox | |
|---|---|---|
| Shortcut | Cmd/Ctrl + G |
Cmd/Ctrl + B |
| What it is | a coloured frame | a separate graph |
| Do the blocks move? | no, they stay put | yes, they change graph |
| Effect on the application | none | a graph call at runtime |
| Reusable elsewhere? | no | yes, as often as you want |
| Does deleting destroy the contents? | no, the frame only | yes, it is a whole graph |
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.