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

# Add character

# 🟧 Add character

${frame}[Video: anatomy of the Add character block](https://celestory-docs-videos.netlify.app/en/anatomie-bloc/addcharacter.html)

The **Add character** block brings a character onto a Visual Novel stage, at a given slot and depth, with an entrance animation.

This is the block that makes a character exist on screen. Until it has run, the character only exists in the module settings: the Move character, Change mood, Flip character and Remove character blocks have no effect on it.

## 📥 Inputs

*   **in (Flow)**: Entry point. As soon as the flow arrives, the character enters the stage; the flow resumes once the entrance animation is over.
*   **character (Character reference)**: Dropdown listing the characters declared in the module settings (Characters tab). A second dropdown, "Select a mood", picks the mood shown on arrival.
*   **slot (Number, default 1)**: Horizontal slot number, from 1 up to the number of "slots" declared by the Scene block. An out-of-range value is clamped back into the grid (0 or 12 in a 3-slot scene give slot 1 or slot 3).
*   **depth (Number, default 1)**: Depth layer number, from 1 up to the number of "depth" layers of the Scene block. Each extra layer shrinks the character by 10%: depth 1 = 100%, depth 2 = 90%, depth 3 = 80%.
*   **mirror (Boolean, default false)**: Displays the character flipped horizontally, so that it faces the other way.
*   **transition (Choice, default "instant")**: How the character arrives. `instant` shows it at once; `from above`, `from the right`, `from below` and `from the left` slide it in from the matching edge; `fade out` fades it in (the label is misleading: on entrance it really is a fade-in).

This block has **no** duration input: the entrance animation length comes from the module setting "Character entrance transition duration" (0.8 s by default).

## 📤 Outputs

*   **out (Flow)**: The flow resumes once the character is in place and its entrance animation has played. Typically chain into a Dialogue block, or into another Add character block to compose the stage.

## 💡 Example

**Scenario: the bookseller walks in**

1. A Scene block shows the inside of the shop, with 3 slots and 2 depth layers.
2. A first Add character block puts "Customer" on slot 1, depth 2, mood "Neutral", transition `instant`: he is already there, in the background, slightly smaller.
3. The player picks "Push the door open".
4. A second Add character block puts "Bookseller" on slot 3, depth 1, mood "Cheerful", transition `from the right`: she slides in from the right edge of the screen over 0.8 s.
5. The flow continues into a Dialogue block where the bookseller speaks.

## ⚙️ Technical Details

*   **Internal ID**: `addCharacter`
*   **A Scene block is required upstream**: the grid of slots and depth layers is created by the Scene block. If no Scene block has run in the module, Add character — like the other four character blocks — does strictly nothing, with no error message. Conversely, every new Scene block clears the stage: all characters present leave with a fade out.
*   **The mood *is* the image**: for an image-based character (the common case), what shows on screen *is* the image of the selected mood. With no mood picked, or if the mood has no image, the character does take its slot on stage but **nothing appears**. Moods are created in the module settings → Characters tab → pick the character → "Moods" section → "Add mood" button: each mood is a name plus an Image resource. For a Spine character ("Use Spine" checkbox), the section is called "Animations" and the mood name must match a skeleton animation name exactly.
*   **Slot already taken**: if another character occupies the target slot, it is first moved to the first free slot on the same depth layer, failing that to any free slot on the stage. If the stage is full, it is removed with the chosen transition.
*   **Adding the same character twice**: the block does not check whether it is already on stage, and a second copy is created on screen. Use Remove character before bringing it back.
*   **Order of application**: slot → mirror → mood → entrance slide. For an image-based character, the mirror set here flips the mood texture, whereas Flip character animates the sprite scale: combining the two gives an inconsistent result, worth checking in the player.
*   **"Disable every transition and delay" setting**: when it is on in the module settings, every duration drops to 0 and characters appear instantly.
*   The module's delay panel shows the "Character entrance transition duration" field **twice**: both drive the same setting.

## 🔗 See also

*   **Scene**: to run first, to declare the number of slots and depth layers.
*   **Remove character**: to take an added character off stage.
*   **Move character** / **Change mood** / **Flip character**: to act afterwards on a character already on stage.

---

*Documented version: v1*