🧱 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.

🎭 One picture to hold it all: the theatre

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

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

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

⚠️ 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.

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.

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. 🚀

Updated on: 23/09/2026