🪦 Legacy blocks: they accept everything, and show nothing

The block-picker doesn't separate current blocks from legacy ones. An older block, replaced since by another, stays listed in the same place — sometimes under a name shorter and more tempting than the current one. You can wire anything into it: the project compiles, the validator stays green, and nothing shows up. This article walks through the one proven trap — backgrounds — and gives you a method for spotting others before they cost you an hour.

🎭 The trap: "Stage" is not "Background"

For a full-screen background, two blocks in the add-list look alike:

Stage's input point isn't called "image" but stage: it expects the ID of a background chosen in the module's configuration, not a file. Wiring in the output of a Load image or Background image block is accepted without any warning. The project compiles. The validator stays green.

At playtime, the reader looks up a background matching the received ID in the module's list of backgrounds. Since that ID matches nothing you wired in, no background is found: the reader falls back to the module's default background (often empty), without even firing a network request to fetch your image. Nothing loads, and strictly speaking nothing fails either: the expected value was simply never there.

The right block for a full-screen background is Background (switchBackground) — see Displaying a background: the three-block chain.

🔍 Why this trap is hard to spot on your own

• The name alone isn't enough. Another block, in a different module type (Visual Novel), is also called "Scene" and does have a real entry in the documentation. Searching for "Scene" in the docs therefore returns a result — but for a different block, in a different module. An article existing under the same name isn't proof that your block, in your module, is documented.
• No type warning appears when you wire it up. The graph doesn't block the connection, doesn't color it differently, doesn't warn you when an output's type doesn't match the input it's plugged into.
• The validator only checks whether the graph compiles, never whether the render is correct.

Before wiring in a block that feels old

1. Open Documentation/Blocs/BlocsV3/FR and look for an entry matching exactly the block's name and the context (Chatbot, Visual Novel…) you're using it in.
2. If two blocks in the add-list seem to do the same thing, always prefer the one whose input is a concrete value you just prepared (an image, a text) over one whose input is a reference into a list stored elsewhere (stages, characters…) — it's this second kind of input that fails silently when you wire the wrong thing into it.
3. After adding any visual block, open Test play right away, before moving on to the rest of the graph. A missing background is spotted in ten seconds at that point; it's spotted much more slowly an hour later, buried in the rest of the story.

📋 What I can prove

Exactly one block in the Chatbot module's catalogue matches, with certainty, the pattern "legacy, accepted without error, invisible in use, no entry for this specific block":

• Stage (background) — replaced by Background (switchBackground).

To reach this list, I compared every block's displayed name in the Chatbot module against the full set of entries in Documentation/Blocs/BlocsV3/FR. With one exception (the one above, hidden by the name collision with the Visual Novel's own Scene block), every block currently named in the Chatbot interface has a matching entry — including recent additions such as the "object" family (Get/Destructure/Set in/Remove from an object…), the AI-request blocks, or the MCP block, none of which link out to the online help center but all of which do have a local entry.

❓ What I'm not sure about

A handful of block types (among them go, entrance, portal, end, score, scoreboard, storeData, loadData, editConfig) have no translated name in the interface at all — no documentation entry, and no visible label I could find in the translation code. I could not confirm, without opening the live editor, whether the add-list actually offers these to users in that form, or whether they are internal blocks not meant to be placed by hand. The 06/09 audit referenced alongside this article counted nine such blocks in total; I could only establish proof for one, by this method (comparing the block catalogue against existing documentation entries). If you come across one of these types in the add-list, treat it with the same caution as Stage: check its documentation entry before trusting it, and test right after wiring it in.

→ Next step: read Displaying a background: the three-block chain for the correct method, block by block.

Updated on: 21/09/2026