> ## 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).

# Connecting Two Blocks: The Wire, the Triangles and the Circles

# 🔗 Connecting Two Blocks: The Wire, the Triangles and the Circles

A **wire** is the curved line that connects a point on one block to a point on another: it, and it alone, decides what happens after what, and what each block receives to do its job. 🧵

Everything else in Celestory — the blocks, their settings, the modules — only exists because wires connect them. It's therefore the single most central notion in the tool, and also the one nobody ever took the time to define.

🔺 **A matter of vocabulary, settled here once and for all.** Depending on the page, you'll read "story wire," "story flow," "execution wire" or "execution flow": four names for the same thing. The interface itself uses none of the four: it says **connection** ("Split connection," "Remove connection"). In this article, we say **wire** for the line, and **flow** for what travels along it when we're talking about the story's sequence.

---

${frame}[Video: Connecting Two Blocks](https://celestory-docs-videos.netlify.app/en/construction-graphe/connecting-two-blocks.html)

## 🍳 The analogy: the kitchen brigade

Picture a restaurant kitchen. Two very different things flow through it, and mixing the two up is the source of nearly every beginner mistake.

-   🎫 **The order ticket** passes from hand to hand: the head chef gives it to the cook, who gives it to the pastry chef. Only one cook holds it at a time, and whoever has it is the one working **right now**. That's the **flow**.
-   🥕 **The ingredients** don't pass from hand to hand: they sit there, and each cook goes and fetches the one they need, exactly when they need it. Nobody "hands off" to a carrot. That's the **value**.

In Celestory, both of these flows travel along wires that look alike, but they don't plug into the same places — and the tool draws the sockets differently to tell you so. 🎯

---

## 🔺⚪ How to read a block's points

Every socket on a block is called a **point**. Its **shape** tells you what it carries, its **fill** tells you whether it's been served.

| Shape | Technical type | What it does |
|---|---|---|
| 🔺 Triangle | `Stream` (**Stream point**) | Hands off control. The block runs when the flow reaches it, then passes it on to what follows. |
| ⚪ Circle | `Value` (**Value point**) | Carries a piece of data: a number, a text, an image, a list… Triggers nothing. |
| ⚪ Circle | `Variable` | A particular kind of value: the variable **itself**, not just its content — so it can be modified. |

-   **Filled shape** = this point is served. For an output, that means at least one wire leaves from it. For an input, that means a wire reaches it, **or** a value was typed in by hand in the block's editing window.
-   **Hollow shape** = this point is neither wired nor filled in. That isn't necessarily an error: plenty of points carry a default value.

🔺 So there are only **two shapes for three types**: the circle serves both values and variables. The difference isn't visible to the eye — you discover it the moment a link refuses to form.

### 📍 Where these points sit on the block

The two main **Stream points** — the ones called `in` and `out` — aren't filed with the rest: they sit **in the block's coloured header band**, to the left and right of the title, and they carry no label at all. Every other point — whether a **Value point** or a secondary **Stream point** (the **true** / **false** outputs of a Condition block, for instance) — is listed below the band, with its name.

```plain text
       INPUTS  (left)                             OUTPUTS  (right)

           ┌──────────────────────────────────────┐
  ────────▶│ ▶             Pause                ▶ │────────▶      header band: the flow
           ├──────────────────────────────────────┤               (triangles, unlabelled)
  ────────○│ ○  Duration                          │
           └──────────────────────────────────────┘               body: the values
                                                                  (circles, with their name)

           ┌──────────────────────────────────────┐
           │         Random number                │        no triangle: this block
           ├──────────────────────────────────────┤        never takes control,
  ────────○│ ○  from                              │        it only supplies data
  ────────○│ ○  to                     result   ○ │────────○
  ────────○│ ○  decimal                           │
           └──────────────────────────────────────┘

  ▶ = triangle → flow          ○ = circle → value
  filled shape = wired or filled in          hollow shape = empty
```

A block with no triangles at all, like **Random number**, never takes a place in the sequence: it's a **value block**, you plug it into someone else's input. A block with triangles, like **Pause**, is a **flow block**: it slots in between two others. 🧩

---

## 🛠️ Do this right now: three blocks, two wires

In a fresh module, you already have a **Start** block: it's the front door of your story, it exists exactly once per graph, and it has a single output, a triangle.

1.  **Zoom in.** You need to see the points individually, or nothing that follows will work (see the box further down). 🔍
2.  **Add a Pause block** (right-click an empty area of the canvas to open the add menu).
3.  **Pull the first wire:** click the **Start** block's output triangle, hold, and release on the **Pause** block's input triangle. While dragging, the wire is grey; it takes on the colour of the targeted block as soon as the cursor gets near a compatible point. That's your only indicator. 🎨
4.  **Add a Random number block.** Notice: it has no triangle at all. There's no way to place it "before" or "after" anything.
5.  **Pull the second wire:** from its **result** output circle to the **Duration** input circle of the Pause block.

You've just performed the two moves that make up 100% of a Celestory graph: **handing off control** (Start ▶ Pause) and **supplying data** (Random number ⚪ Duration). Your story will now hold a pause for a randomly rolled length of time. 🎲

🔺 If you wire nothing to **Duration** and type nothing in the block's window, the pause lasts **0 seconds**: the point keeps its default value, with no warning whatsoever. The missing ingredient doesn't interrupt the service.

---

## 🚫 When the wire refuses to connect

Celestory checks compatibility in real time and **never creates an inconsistent connection.** That's not the problem: the problem is that it never tells you **why**. ⚠️

⚠️ **The central trap.** When you release a wire onto an incompatible point, **absolutely nothing happens** — no error, no message, no red alert. Instead, a small **"Connect to…"** menu opens under your cursor — the exact same one as if you'd dropped the wire into empty space. Many users close it thinking they fumbled the gesture, never realising their wire was refused.

The four reasons for a refusal, in order of frequency:

1.  **A triangle with a circle.** The rule is absolute: a **Stream point** only connects to another **Stream point**. No exceptions, no automatic conversion.
2.  **Two incompatible data types.** A text into an input expecting an image, for instance. If in doubt, open the block's editing window: the field tied to the point tells you what it expects.
3.  **A locked point.** Some inputs can only be filled in **by hand** and never accept a wire: the **choices** field of a Choice block, the **expression** field of an Expression block, the **format** field of a Format text block, the **graph** field of an Open a graph block… Yet they're drawn as ordinary circles. This is the only case where Celestory finally speaks up: the menu then reads **"No block can be connected to it."**
4.  **Two outputs into the same value input.** A **Value input** only accepts a single wire (see the next section).

### ✅ The right move: drop it in empty space

Rather than aiming for a point and missing, **pull the wire from your starting point and release it on an empty area of the canvas.** The **"Connect to…"** menu opens, and it only lists blocks and variables that are genuinely compatible with that exact point, sorted into **"Most used blocks"** and **"Other blocks."** Pick one: the block is created right where you released, **already wired**. 🪄

It's the safest way to work when you're starting out: you literally **cannot get the type wrong**, since the list is filtered for you. A search field lets you narrow it down further, and pressing **Enter** confirms the first suggestion.

---

## ⚖️ How many wires per point?

The rules aren't the same on both sides, and they apply silently.

| Point | Number of wires | What happens if you plug in another one |
|---|---|---|
| 🔺 Stream output | **Only one** | The old wire is deleted with no confirmation. |
| 🔺 Stream input | As many as you like | Several paths can lead to the same block. That's normal and desirable. |
| ⚪ Value output | As many as you like | The same piece of data can feed ten blocks. |
| ⚪ Value input | **Only one** | The old wire is deleted with no confirmation. |

⚠️ These two silent deletions are a classic cause of a "vanished" story branch: by plugging a block's output somewhere else, you destroyed the previous path. Nothing is displayed. `Cmd+Z` (`Ctrl+Z`) restores everything.

⚠️ **A wire overwrites a typed-in value.** If you had typed a duration by hand in the Pause block's window, wiring something into **Duration** **permanently erases** that entry. The wire always wins against a written-in value.

---

## ✂️ Deleting, cutting, inserting

-   **Deleting a wire**: click it to select it (it turns blue, along with its two blocks), then `Delete` or `Backspace`. Right-clicking the wire offers the same option: **Remove connection**.
-   **Unplugging from the block's window**: double-click the block; next to every wired point, a small cross lets you remove that specific wire — useful when wires overlap on screen and you can't click the right one.
-   **Inserting a block in the middle of a wire**: right-click the wire, then **Split connection**.

⚠️ **The double-click trap.** A double-click doesn't do the same thing depending on what's under the cursor: on a **block**, it opens its editing window; on a **wire**, it inserts a **Connector** block (a plain white relay) at the clicked spot and re-splices both halves onto it. When a wire passes over a block, the block wins. A Connector that "appeared on its own" in the middle of your graph almost always comes from this.

🔺 The **Connector** only has two triangles: it exists solely for the **flow**, where it lets you neatly route around a crowded area. Don't use it on value wires.

---

## 🔍 Two physical conditions

⚠️ **Below 50% zoom, wires can no longer be drawn.** At that level, Celestory renders blocks as plain coloured rectangles, with no visible points: clicking and dragging a block **moves it** instead of pulling a wire. If your gesture produces nothing but a block sliding around, it's not you, it's the zoom. Zoom in and try again.

🔺 Points are very small, and Celestory grabs whichever point is **closest to the cursor**. On a crowded block, get into the habit of zooming in properly before wiring, rather than aiming pixel-perfect.

---

## 🧠 What to remember

-   A **wire** connects two points. Depending on the page, you'll also see it called story flow, execution wire or connection: it's the same thing.
-   🔺 **Triangle = flow**: it hands off control. ⚪ **Circle = value**: it carries a piece of data.
-   A triangle **never** connects to a circle.
-   **Filled = served, hollow = empty.**
-   On a refusal, **nothing is displayed**: drop the wire in empty space and let the **"Connect to…"** menu offer you what's compatible.

---

→ Next step: now that you know how to hand off control from one block to another, learn to hand it off to **several different places** with "Votre premier choix : le lecteur décide, l'histoire bifurque". 🌿