> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://documentation.celestory.io/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Organising a large graph: groups and blackboxes # 🗂️ 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. 1. The selected blocks are **moved** into it — they leave the original graph. 1. Two blocks appear there: **Input *name*** on the left and **Output *name*** on the right. 1. Every connection that crossed the border of your selection becomes a **point** on those two blocks. 1. In the space left behind, an **Open a graph** block is dropped in, already wired to the same neighbours. 1. 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.