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

# Project, Module, Graph, Block: What Contains What

# 🧱 Project, Module, Graph, Block: What Contains What

You've just opened Celestory, and four words keep coming up: **project**, **module**, **graph**, **block**. They name four nested levels, from the largest to the smallest. Until you've sorted them out, the left sidebar looks like a list of folders with no logic to it. Once the order clicks, everything else about the tool becomes readable. 🎯

This article doesn't show you how to create anything: it only lays out the **mental model**. Budget five minutes, and keep the diagram handy.

---

${frame}[Video: Project, Module, Graph, Block](https://celestory-docs-videos.netlify.app/en/panorama-ia/projet-module-graphe-bloc.html)

## 🎭 One picture to hold it all: the theatre

This whole story fits inside one comparison, and we'll keep it all the way through:

| In Celestory | At the theatre |
|---|---|
| The **project** | The theatre: the building, and everything it houses. |
| A **module** | A show on the bill, with its own cast and its own sets. |
| A **graph** | The show's cue sheet: the sheet that says what happens, and in what order. |
| A **block** | One line of that cue sheet: a line of dialogue, a scene change, a question asked of the audience. |
| A **variable** | The whiteboard in the lobby: there's only one, and any show can read it. |

Remember the last row above all. **The whiteboard is in the lobby, not in the dressing rooms** — even though Celestory's tree view suggests otherwise. That's the central trap of this article, and we come back to it below. ⚠️

---

## 🗺️ The diagram of how it actually nests

```plain text
PROJECT
│
├── PROJECT VARIABLES ◀───────────────────────────────────────────────┐
│      one single flat list, valid everywhere                         │
│      ├─ playerFirstName  (Text)                                     │
│      ├─ healthPoints     (Number)                                   │
│      └─ Chapter 2        (folder: visual sorting, nothing more)     │
│                                                                      │
├── MENUS   home · pause · HUD · overlay                              │
│                                                                      │
├── MODULES   (1 minimum)                                             │
│   │                                                                 │
│   ├── "Intro"  —  Chatbot template                                  │
│   │     ├── Start graph                                             │
│   │     │     [Start] ──wire──▶ [Dialogue] ──wire──▶ [Choice]       │
│   │     │     + groups: boxes drawn around blocks                   │
│   │     ├── "Score calculation"  ← another graph of THIS module     │
│   │     ├── Characters            ← belongs to THIS module          │
│   │     ├── Stages                ← belongs to THIS module          │
│   │     ├── Context   belongs to no one: it's a shortcut ───────────┘
│   │     └── Module settings
│   │
│   └── "Chapter 1"  —  Visual Novel template
│         same structure, DIFFERENT characters and stages
│
└── GLOBAL GRAPHS
       attached to no module, callable from any of them
```

The line running up from **Context** to **Project variables** is the only arrow in the diagram. It says it all: this row is filed under a module, but it doesn't belong to it.

---

## 🏛️ The project: the topmost level

The project is what you open when you click a tile from your home page. There's nothing above it.

Filed **directly in the project**, next to the modules rather than inside them:

-   the **variables** (and their sorting folders);
-   the **menus**: the screens outside the story — home, pause, settings, HUD;
-   the **labels**, the **translations**, the **files** in your library;
-   the settings for **connecting to external services** and the export options.

In other words: **anything not explicitly filed inside a module is filed in the project.** That holds true right down into the save file, where the list of modules and the list of variables are two neighbouring lists, at the same level.

---

## 🎬 The module: one show, one template

A module is a **complete, playable application**, with a look of its own. The left sidebar, titled **Modules**, lists one per folder.

When you create a module, you choose its **template** from two options:

-   **Chatbot** — the application looks like a conversation, messaging-app style;
-   **Visual Novel** — the application looks like a full-screen illustrated book.

🔺 This choice isn't cosmetic: it decides which blocks are available in the module's graphs, and what its settings window contains. A Chatbot module and a Visual Novel module don't share the same catalogue of building blocks.

A project contains **at least one module** — the delete button simply vanishes once only one is left.

### What the sidebar shows under a module

| Row in the tree | What the click opens | Actual scope |
|---|---|---|
| **Start graph** | The graph the module begins with. It has no editable name. | The module |
| *(your named graphs)* | The other graphs you've added to this module. | The module |
| **Characters** | The Characters tab of the module's settings. | The module |
| **Stages** | The backgrounds tab. **Only appears on a Chatbot module.** | The module |
| **Context** | The **"Project variables"** window. | ⚠️ **The whole project** |
| **Module settings** | The module's Settings window (appearance, styles). | The module |

> ⚠️ **The "Context" trap**
> Four of these five rows do name something that belongs to the module. The fifth lies about its scope.
> **"Context" is not this module's context.** It's a plain shortcut to the project's variable list — the exact same window as the keyboard shortcut `Cmd+Shift+V` (`Ctrl+Shift+V` on Windows). Open it: its title reads, in black and white, **"Project variables."**
> Concrete consequence: if you click "Context" under the *Intro* module and then create a variable, it's visible and editable from *Chapter 1*, and from every other module you create afterwards. There is **no way** to scope a variable to a single module.

---

## 🕸️ The graph: the show's cue sheet

A graph is a large blank page (no grid, no snapping) where you drop **blocks** and connect them with **wires**. This is where all the logic lives: what gets said, what gets asked, what gets calculated, what gets decided.

A graph contains exactly three kinds of things:

-   **blocks** — the bricks of action;
-   **connections** (the **wires**) — they say which block follows which;
-   **groups** — plain coloured, named boxes you draw around a bundle of blocks to keep your bearings. A group changes nothing about how things play out; it just tidies up.

### The start graph and named graphs

The **start graph** is created at the same time as the module, and it contains a single block: **Start**. It's the entry point: when the module launches, execution begins there.

🔺 The **Start** block is unique within a graph: Celestory refuses to add a second one, and also refuses to delete the one that's there.

You create every other graph yourself (**Add ▸ Add graph** button), and you give it a name. These don't start with a **Start** block but with an **Input** / **Output** pair: they're sub-parts you call from another graph, using the **Open a graph** block, and they hand control back once they're done. Handy for pulling a long calculation, or a repeated scene, out of the main cue sheet.

> 🔺 **Who can call whom?**
> From a graph inside a module, the **Open a graph** block only offers you: graphs **from the same module**, and **global graphs**. Graphs from another module never appear in the list. A module doesn't go borrowing from its neighbour.

---

## 🌍 Global graphs: the universal acts

Right at the bottom of the sidebar, a **Global graphs** folder gathers the graphs attached to **no** module. These are your all-purpose acts: any module can call on them.

You create one by choosing **"None"** in the *Module* dropdown of the add-graph window. You can also drag an existing graph from a module into this folder.

> ⚠️ **Making a graph global destroys part of its content**
> A global graph has to be able to run inside a Chatbot module just as well as a Visual Novel one. So it can only contain blocks common to both.
> When you drag a graph from a module into **Global graphs**, Celestory warns you, then **deletes every template-specific block** — the Dialogue, Choice, Notification blocks and their like all disappear, along with the wires that led into them. Only neutral blocks (conditions, variables, calculations, service calls) survive.
> Check the graph's content carefully before accepting. The operation is undoable on the spot (`Cmd+Z`), not three moves later.

🔺 Dragging a graph from one module **to another module** destroys nothing — but Celestory only allows it if both modules share the **same template**. Chatbot to Chatbot: fine. Chatbot to Visual Novel: the drop is refused.

---

## 🔑 What's shared, and what isn't

This is the table to remember. It answers 90% of the "wait, why can't I find…?" moments of your first few days.

| Element | Shared across modules? | Where it actually lives |
|---|---|---|
| **Variables** | ✅ Yes, all of them, all the time | The project — one single flat list |
| **Menus** (home, pause, HUD…) | ✅ Yes | The project |
| **Labels, translations, files** | ✅ Yes | The project |
| **Global graphs** | ✅ Yes | The project, outside any module |
| **Characters** | ❌ No | The module |
| **Stages / backgrounds** | ❌ No | The module (Chatbot only) |
| **Module settings and styles** | ❌ No | The module |
| **Graphs attached to a module** | ❌ No | The module |
| **Blocks, wires, groups** | ❌ No | The graph that contains them |

Three consequences you wouldn't guess:

1.  **Variable folders don't wall anything off.** You can sort your variables into folders, even folders inside folders. That's purely visual tidying, nothing more: a folder doesn't make a variable private, or scope it to a module.
2.  **Deleting a module doesn't delete its variables.** Its graphs go with it; the variables those graphs used stay behind in the project's list, orphaned. Cleaning them up is on you.
3.  **Exporting a module goes looking for variables elsewhere.** When you export a module to a file, Celestory scans its blocks to collect the variables they use — precisely because those variables aren't inside it.

---

## 🚪 Moving from one module to another

A module doesn't chain into the next one on its own: nothing connects two modules the way a wire connects two blocks. There are three ways to designate which module should open.

| From… | The setting | What it does |
|---|---|---|
| **A graph** | The **Open module** block, *Module* field | Switches to the chosen module, mid-story. It offers every module in the project. |
| **A menu** | The **Start** button element, *Module to open* setting | Launches the chosen module from a home screen. |
| **The export** | The *Starting module* (or *Starting menu*) choice | Decides what the exported application starts with. |

In all three cases, it's genuinely you who picks **which** module. None of these settings is locked to the first module in the list — the first module is only the default value offered, changeable in a dropdown.

> 🔺 **Variables carry over across a module switch**
> When an **Open module** block switches you over, the current values don't move: the score earned in *Intro* is still there in *Chapter 1*. That's normal behaviour, and it's the whole point of having one shared list of variables.
> The only exception is the **Reset the variables** toggle on a menu's **Start** button: switched on, it resets every variable to its original value at launch. That's what you want on a "New game" button, and definitely what you don't want on a "Continue" button.

---

## 🧭 The three words nobody explained to you yet

You'll run into them as soon as you open your first graph:

-   **Block** — a brick dropped onto the graph. It does one thing: show a line, ask a question, compare two values.
-   **Point** — a small dot on the edge of a block. The points on the left are what the block receives, the ones on the right are what it gives out.
-   **Wire** — the line you drag from one point to another to say "and then."

These three have their own article: **Connecting Two Blocks: The Wire, the Triangles and the Circles**. It explains why some points are triangles and others circles, and why certain connections get refused.

---

## ✅ The summary in five sentences

1.  A **project** contains **modules**, and beside them a list of **variables** shared by all of them.
2.  A **module** is a playable application, built on a template (Chatbot or Visual Novel), with its own characters, stages and settings.
3.  A **graph** is the cue sheet: **blocks** connected by **wires**. Every module has its start graph, plus the named graphs you add.
4.  **Global graphs** belong to no one and serve everyone — at the cost of only holding neutral blocks.
5.  Under a module, the **Context** row opens the variables of the **whole project**: the label lies about its scope.

---

→ Next step: move on to practice with **Your First Project: From Blank Page to First Screen**, which walks through these four levels in the order you'll actually meet them. 🚀