Capsule VN Engine

Part I: Foundation

1. Welcome to Capsule VN Engine

Capsule VN Engine is a complete visual novel creation environment that transforms your stories into playable, distributable games — all within a single, self-contained file.

1.1 Vision

We built Capsule for creators who want to focus on story, not syntax. Every feature exists to remove friction between your imagination and your audience. No installation. No dependencies. No server required. Write, preview, export, share.

The engine embraces a monolithic philosophy: your entire game — code, assets, and runtime — lives in one HTML file. This guarantees:

• Zero deployment complexity: Double-click to play
• Universal compatibility: Runs in any modern browser
• Permanent preservation: No broken links, no deprecated platforms
• True ownership: Your game, your file, forever

1.2 Philosophy

Accessible depth. Capsule offers two modes: Simple for immediate creation, Expert for granular control. Switch anytime without losing work.

Visual-first design. What you configure is what you see. Real-time preview, instant feedback.

Narrative integrity. The engine protects your story from technical failure: health checks catch errors before they reach players, rollback systems preserve testing states, and validation ensures your logic holds together.

1.3 Who is Capsule for?

Part II: The Basics

2.1 Your First Project

When you open Capsule, you see three columns:

Creating an initial scene

• Click ➕ New Scene in the left panel
• Choose Narrative scene (for dialogue and atmosphere)
• The scene appears in your list, ready to configure

2.2 Interface and Modes

Simple Mode vs Expert Mode

Switch modes via the Simple / Expert toggle in the header. Your project remains intact; only the interface adapts.

The Tools (Drop-down menu)

Click ⚙️ TOOLS to access:

• Variables — Track game state (score, flags, relationships)
• Actors — Reusable characters with multiple expressions
• UI Custom — Global visual styling
• HUD — On-screen variable display
• Inventory — Collectible and usable items
• Events — Global conditional triggers
• CG Gallery — Unlockable images and videos
• Timeline — Visual story map
• Global Search — Instant cross-project search (Ctrl+Shift+F)
• Stats — Project health and size monitoring

2.3 Fundamental Concepts

The Scene, unit of narration

A scene in Capsule is a self-contained narrative moment. It can:

• Display dialogue with characters
• Show a background image
• Play music and sound effects
• Present choices to the player
• Execute logic (variables, conditions)
• Transition automatically to another scene

The Reading Flow

[start] → [scene A] → [scene B] → [choice 1] → [scene C]
                              ↘ [choice 2] → [scene D]

Capsule follows connections you define. No connection = the story pauses (intentional for endings, problematic elsewhere).

Variables: your story's memory

Variables store information across scenes:

Access a variable in dialogue with {variableName}.

Concrete Example

In a romance scene, display the player's chosen name:

"Good morning, {playerName}. Did you sleep well?"

If playerName contains "Jordan", the player sees: "Good morning, Jordan. Did you sleep well?"

Part III: Creating a Story

3.1 Scenes

Scene Types

Configuring a Narrative Scene

Visual & Sound section:

• Background: Image or video (16:9 recommended, 1920×1080 optimal)
• Transition: Animation between this scene and the previous
• Effect: Atmospheric overlay (rain, snow, particles, etc.)
• Overlay: Additional visual layer (screen effects)
• Music: Background track (loops automatically)
• SFX: One-shot sound effect on scene entry
• Filter: Color grading preset

Dialogue Appearance:

• Font: Typography family
• Box Shape: Geometry of dialogue containers
• Colors: Border, background, and text for both dialogue and name boxes

Best Practices: transitions

Match transition style to narrative rhythm:

• cut — Abrupt changes, action, tension
• fade_black — Time passing, chapter breaks
• slide_left/right — Spatial movement, scene shifting
• iris_in/out — Dramatic reveals, dream sequences

Logic Scenes (Expert)

A Logic Scene has no visual presence. It executes instantly:

• Check ⚡ LOGIC SCENE in the scene options bar
• The scene disappears from visual preview
• Configure Actions to modify variables
• Set Auto Next Scene for immediate continuation

Example: simplified combat system

Scene combat_check (Logic):

• Action: force = force + dice(1,6) (roll 1-6, add to strength)
• Condition: if force >= 10, go to combat_win
• Else, go to combat_lose

3.2 Dialogues

Structure of a dialogue line

Each dialogue block contains:

• Speaker: Character name (optional — leave empty for narration)
• Text: The spoken content, supporting formatting tags

Text Formatting

Variables in dialogue

Insert {variableName} anywhere in text. Capsule replaces it with the current value.

Complete Narrative Example

Variable: gold = 150

Dialogue: "You have {gold} gold coins in your pouch."

Player sees: "You have 150 gold coins in your pouch."

Later, after gold = gold - 50:

Same dialogue displays: "You have 100 gold coins in your pouch."

Actor Syntax: {actor:id}

Reference an actor's display name dynamically:

Variable: heroName = "Alexandre"

Actor configuration:
- ID: hero
- Display name: {actor:hero} → resolves to "Alexandre"

Dialogue: "My name is {actor:hero}."
Player sees: "My name is Alexandre."

This decouples narrative reference from actual name, enabling player customization.

3.3 Narrative Flow

Automatic Navigation

Set Auto Next Scene (ID) to continue immediately after the last dialogue line. Ignored if choices exist.

Navigation via Choices

Choices override auto-next. Each choice defines:

• Text: Button label
• Target: Destination scene
• Optional: Conditions, actions, inventory operations

Backtrack (Previous)

The Previous button navigates backward through dialogue history, or to the previous scene if at the first line.

Part IV: Choices and Consequences

4.1 Simple Choices

The foundation of branching narrative.

Configuration:

• Click ➕ Choice in the Choices section
• Enter Button text (what the player sees)
• Select Target scene (where the choice leads)

Example: First Decision

Scene: tavern_arrival

• Choice 1: "Order a drink" → tavern_drink
• Choice 2: "Ask about the stranger" → tavern_inquiry
• Choice 3: "Leave immediately" → tavern_leave

4.2 Conditional Choices

Choices can appear, disappear, or change based on game state.

Variable Conditions

Locked Choice Styles

When a condition is false, choose how the choice appears:

Example: Narrative Locked Choice

Choice: "Unlock the gate" (requires hasKey = true)

If locked: Display 🔒 "Unlock the gate" with alternative text: "You need a key to open this."

Player understands why they cannot proceed, creating narrative tension.

Alternative Text

When locked, display different text to explain the barrier:

• Normal text: "Enter the secret room"
• Alternative (locked): "A heavy iron door blocks your way"

4.3 Invisible Choices

Set style to Hidden for choices that only appear when conditions are met. Creates emergent narrative paths:

Example: Secret Detection

Hidden choice: "Notice the hidden compartment" (requires perception >= 8)

Players with high perception see the option. Others never know it existed.

4.4 Choice Actions

Execute operations when a choice is selected:

Example: Narrative Consequence

Choice: "Defend the village"

• Action: heroism + 10
• Action: villageSaved = true
• Target: village_aftermath

Later scenes check villageSaved to determine available NPCs and dialogue.

Part V: Advanced Logic

5.1 Typed Variables (Expert)

Capsule v1.6.3+ introduces explicit variable types for safer logic.

Click the type icon to change. The engine validates operations:

• Addition/subtraction only on Numbers
• Boolean variables present true/false dropdowns

5.2 Triggers (Expert)

Triggers execute automatically when conditions are met at scene entry or exit.

Structure of a Trigger

WHEN: [Start of scene / End of scene]
IF: [variable] [operator] [value]
THEN: [Action 1, Action 2, ...]

Trigger Action Types

Example: Security Trigger

Scene: throne_room

Trigger (Start):

• IF: hasRoyalSeal != true
• THEN: Go to throne_denied

Players without the seal are automatically redirected before seeing the throne room.

Evaluation Order

Triggers process top to bottom. The first Go to Scene action stops evaluation (short-circuit behavior).

5.3 Logic Scenes

Invisible routing nodes for complex logic.

Use cases:

• Hub scenes: Central decision point with multiple conditions
• Variable normalization: Ensure consistent state before branching
• Randomization: Dice rolls determining paths
• Progression checks: Level requirements, item verification

Example: District Hub

Scene district_hub (Logic):

5.4 Inventory (v1.7.0)

Complete item management system.

Defining Items

Each item specifies:

• ID: Code reference (lowercase, no spaces)
• Display Name: Player-visible label
• Icon: Emoji or single character
• Description: Flavor text shown on inspection
• Max Stack: Maximum quantity (1 for unique items)
• Stackable: Whether multiples can be held
• Consumable: Whether using removes the item

Inventory Operations

Inventory Conditions

Choices and hotspots can require items:

IF HAS: "ancient_key" (quantity: 1)
IF NOT HAS: "cursed_amulet"
IF COUNT: "gold_coin" >= 50

Example: Narrative Economy

Item: gold_coin (stackable: 99, icon: 🪙)

Choice: "Purchase the map" (requires 20 gold_coin)

On click: Remove 20 gold_coin

On click: Add treasure_map

The player sees their coin count decrease in real-time if HUD is enabled.

5.5 Interactions: Hotspots (v1.7.0)

Point-and-click exploration zones.

Visual Configuration

Hotspot Actions

Hotspot Conditions

Hotspots can be disabled based on:

• Variable conditions: puzzleSolved = true
• Inventory conditions: hasLantern = true

Example: Exploration Scene

Background: Ancient library

5.6 QTE: Quick Time Events (v1.8.0)

Timed decisions for tension and action sequences.

Configuration

Visual feedback

• Progress bar depletes horizontally
• Last 30%: Bar turns red, pulses urgently
• Timer text counts down in seconds

Example: Action Sequence

Scene: bridge_collapse

QTE: 5 seconds

Timeout action: Auto-select choice 3 (freeze, leading to bridge_fall)

5.7 Player Inputs: Text Input (v1.8.0)

Collect free-form text from players.

Configuration

Example: Protagonist Customization

Scene: character_creation

Text Input:

• Target: heroName
• Validation: Text
• Title: "What is your name?"
• Placeholder: "Enter your name..."
• Default: "Alex"

Later dialogue: "Welcome to the academy, {heroName}."

Example: Code Puzzle

Text Input:

• Target: doorCode
• Validation: Code (exact match: "7349")
• Title: "Enter the 4-digit code"

Trigger following input checks doorCode and redirects accordingly.

Part VI: Atmosphere and Staging

6.1 Images

Supported Formats

Image Types

6.2 Sounds

SFX (Sound Effects)

• One-shot sounds triggered by scene entry or actions
• Recommended format: OGG Vorbis, 64-128 kbps
• Volume controlled by SFX slider in Options

Music

• Looping background audio
• Automatic crossfade between scenes (if different file)
• Recommended format: OGG or MP3, 128 kbps

6.3 Transitions

6.4 Atmospheric Effects

Effective Combinations

• Heavy Rain + Screen Shake + Fade to Black = Destructive storm, tragic end
• God Rays + Floating Dust + Sakura Petals = Reconciliation scene, ephemeral beauty
• Glitch + TV Static + VHS Scan = Digital horror, fracturing reality

6.5 Complete UI Customization (UI Custom)

Capsule allows global visual customization that automatically applies to all your scenes, eliminating the need to configure each scene individually.

6.5.1 Customization Architecture

The UI Custom system works on two levels:

The "Use default appearance (UI Custom)" checkbox in each scene determines if it inherits the global style or defines its own parameters.

6.5.2 Replacement Images

Import your own images to replace default UI elements. All images are stored in Base64 within the project file, ensuring export autonomy.

Dialogue Box

Concrete Example: Japanese Visual Novel Style

Import a dialogue box image with golden ornaments at the corners, semi-transparent. Set opacity to 0.9 to preserve readability while showing the background.

Result: all scenes with "Use default appearance" enabled automatically display this custom box.

Name Box

Example: Elegant Integration

Create an image with a decorative ribbon that slightly overlaps under the main dialogue box. Position it at opacity 1.0 so it partially masks the main box, creating harmonious layering.

Choice Buttons

Example: Medieval Fantasy Style

Design stone buttons with engraved runes. Import the image — all game choices will adopt this style. The "hover" state retains the image but applies the theme's accent color.

Menu Buttons

Example: Menu/Game Consistency

Use the same texture as choice buttons to unify the experience. The main menu, save screen, and options screen automatically share this image.

Game Title

Example: Professional Logo

Design your title in design software (Photoshop, Illustrator, Figma) with light effects, gradients, or custom typography. Export as transparent PNG. Import into UI Custom — the text "MY GAME" is replaced by your image.

Major advantage: The title can extend beyond text limits, include illustrations, and use effects impossible in pure CSS.

6.5.3 Default Dialogue Appearance

Define a color palette and shapes applied automatically to all scenes checked "Use default appearance".

Configurable Parameters

Available Box Shapes

Example: Consistent Art Direction

Project: psychological thriller

UI Custom Configuration:

• Font: 'Courier New', monospace (typewriter = documents, archives)
• Shape: shape-minimal (tension, nothing superfluous)
• Dialogue: white border, black background 90%, light gray text
• Name: blood red border, transparent background, red text

Result: every new scene created with "Use default appearance" immediately inherits this visual identity. No manual configuration required.

6.5.4 Customization Workflow

Step 1: External visual design

Create your assets in your tool of choice:

ui_assets/
├── dialogue_box.webp      (1600×280, semi-transparent bg)
├── name_box.webp          (400×60, left ornament)
├── choice_button.webp     (600×80, stone texture)
├── menu_button.webp       (600×80, same texture)
└── title_logo.webp        (800×200, logo with effects)

Production tips:

• WEBP format for compression without visible loss
• Alpha transparency for overlays
• Test on both light AND dark backgrounds before finalizing

Step 2: Import into Capsule

Open ⚙️ TOOLS → UI Custom

For each element:

• Check "Use Custom"
• Click 📂 Choose File or paste a URL
• Adjust Opacity if necessary
• Observe the real-time update in the preview

Step 3: Define global colors

In the "Default Dialogue Appearance" section:

Step 4: Application to scenes

6.5.5 Advanced Use Cases

Temporary Variation (flashback, dream)

Problem: You want a different style for dream sequences, but keep the main style as default.

Solution:

• Configure UI Custom with your main style (reality)
• For dream scenes:
  • Uncheck "Use default appearance"
  • Define locally: sepia filter, "Elegant" shape, cursive font
• At the end of the dream, return to a "Use default appearance" scene — normal style reappears instantly

Multi-protagonists (dynamic name colors)

Problem: Two playable characters with distinct color palettes.

Solution:

• UI Custom defines base style (shapes, fonts)
• Per scene, adjust locally:
  • Protagonist A scenes: emerald green name
  • Protagonist B scenes: electric blue name
• Both share the same box geometry (consistency), but differ by accent color (differentiation)

Implicit Responsive Adaptation

UI Custom images are:

• Centered automatically
• Resized as cover or contain depending on the element
• Preserved in ratio on export

6.5.6 UI Custom Elements Summary Table

6.5.7 Complete Example: Full Project Re-skin

Context: You created a modern VN (contemporary, office, city) and want to transform it into medieval fantasy without recreating all scenes.

Before (modern):

• Font: Segoe UI
• Shape: Standard
• Colors: corporate blue, gray
• No custom images

Transformation:

UI Custom Panel

• Import dialogue_parchment.webp (aged parchment)
• Import name_banner.webp (fabric banner)
• Import choice_stone.webp (engraved stone)
• Import title_fantasy.webp (logo with runes)
• Change font: Palatino Linotype
• Change shape: Gem
• Colors: gold (#FFD700), brown (#3E2723), cream (#FFF8E1)

Existing Scenes

• All had "Use default appearance" checked
• Instantly: the entire project adopts the fantasy aesthetic

Spot Adjustments

• Royal Throne Scene: uncheck, name in royal purple
• Tavern Scene: uncheck, name in moss green

Result: 4 minutes of configuration, fully re-skinned project, visual consistency guaranteed.

Part VII: Reliability and Quality

7.1 Project Health Check

Capsule analyzes your project in real-time and flags problems.

Alert Types

Automatic Checks

Best Practices: Health Check Workflow

• Create your narrative structure (empty connected scenes)
• Check Health Check — resolve connection errors
• Add content (dialogue, images)
• Check regularly — the panel updates in real-time

7.2 Preventing Errors

Runtime Safeguards

Exceeding a limit stops execution with an explicit error message (Dev mode).

7.3 Best Practices

Narrative Organization

Naming convention:

chapter_01_tavern_intro
chapter_01_tavern_choice
chapter_01_tavern_combat
chapter_01_tavern_aftermath

Hub and spoke:

        [hub_district]
       /      |      \
[market]  [temple]  [docks]
   |          |         |
[return]---[return]---[return]
    \         |         /
     \        |        /
      [hub_district] (next chapter)

Variable Management

Part VIII: Export and Share

8.1 HTML Export

Click 💾 EXPORT to generate a standalone HTML file containing:

• Complete game engine (minified JavaScript)
• All embedded assets (Base64 encoded)
• Story data and configuration
• Save/load system (localStorage)

8.2 Browser Compatibility

8.3 Distribution

Web Hosting

Upload the HTML file to:

• GitHub Pages (free)
• itch.io (free, VN community)
• Netlify/Vercel (free, global CDN)
• Your own server

Direct Sharing

• Email (if < 10 MB after compression)
• Cloud storage (Google Drive, Dropbox with direct link)
• Messaging (Discord, Telegram — drag and drop)

Part IX: Designing a Complex VN

9.1 Structuring

Recommended Architecture

[main_menu]
    ↓
[start] ───┬──→ [intro_sequence]
           ↓
    [chapter_1_hub] ←——————┐
       /    |    \         |
      ↓     ↓     ↓        |
   [A]→[B] [C]→[D] [E]→[F] |
      \     |     /        |
       └→[chapter_1_end]——─┘
                ↓
        [chapter_2_start] ←—— (via nextFile: chapter2.html)

Multi-chapters

For large stories, use Jump to HTML File:

• Create chapter1.html, chapter2.html, etc.
• In the last scene of chapter N:
  • Enable Auto-Start in config
  • Set Jump to HTML File: chapter2.html
• Variables are automatically transferred

Example: Chapter Transition

Scene: chapter1_finale (Logic)

• Actions: Automatic save of key variables
• Next File: chapter2.html

chapter2.html starts with all variables intact.

9.2 Readability

Scene Rhythm

Choice Density

• Minimum: 1 significant choice every 5-10 minutes
• Maximum: Avoid more than 4 simultaneous choices (paralysis)
• Balance: 70% narration, 30% interaction

9.3 Maintainability

Internal Documentation

Use implicit comments:

• Named logic scenes: check_, hub_, calc_
• Variables with metadata in name
• Choices with explanatory alternative text

Versioning

Export milestones:

• mygame_v0.1_prototype.html
• mygame_v0.5_alpha.html
• mygame_v1.0_release.html

Part X: FAQ & Frequent Errors

10.1 Common Issues

Q: My game is stuck on a black screen

Check that the scene has either dialogue, choices, or a next scene defined. An empty scene without an exit creates a block.

Q: Variables are not displaying in dialogue

Check syntax: {variableName} (no spaces, exact case). Verify the variable is declared in Variables Manager.

Q: Music is not starting

This is normal — browsers block autoplay. Music starts after the first user click. In Auto-Start mode, add a clickable title screen.

Q: My exported file is 50 MB

Compress your assets:

• Images: convert to WEBP, reduce to 1920×1080 max
• Audio: OGG 64-128 kbps
• Video: WebM 720p

Q: Conditional choices never appear

Check the operator: = for equality, not ==. Verify the variable has the expected value (use Dev Mode).

10.2 Runtime Error Messages

10.3 Mobile Optimization

11. Actors

Actors are reusable characters with multiple expressions, eliminating configuration duplication and ensuring narrative consistency.

11.1 Actor Architecture

11.2 Creating an Actor

Steps:

• ⚙️ TOOLS → Actors
• ➕ Create New Actor
• Actor ID: unique technical identifier (lowercase, no spaces)
  • Example: elara, captain_ren, mysterious_stranger
• Display Name: name visible to the player
  • Example: "Elara", "Captain Ren", "???"
• Name Color: name color in dialogues (hex selector)

11.3 Sprite Management (Expressions)

Each actor has a library of interchangeable expressions.

Importing a sprite:

Concrete Example: Complete Creation

Actor: elara

Display Name: "Elara"

Color: #D4AF37 (gold)

Sprites:

Total: 5 expressions to cover the main narrative arc.

11.4 Usage in Scenes

Referencing an Actor

In the Characters section of a scene:

Dynamic Syntax: {actor:id}

Automatically display an actor's Display Name in dialogue:

Variable: heroName = "Jordan"

Actor: hero (Display Name: {actor:hero} → "Jordan")

Dialogue: "My name is {actor:hero}, and I won't give up!"

Player result: "My name is Jordan, and I won't give up!"

Major advantage: Change heroName to "Alex" at the start of the game — all dialogues using {actor:hero} update instantly.

11.5 Advanced Workflows

Actor with changing name

Shared Actor Library

Organize by narrative category:

Main Actors
├── hero (customizable protagonist)
├── companion (constant ally)
└── antagonist (main villain)

Secondary Actors
├── merchant_recurring (comic relief)
├── mentor (guide, likely sacrifice)
└── rival (competition, possible ally)

Episodic Actors
├── village_elder_ch1
├── village_elder_ch2 (same sprite, different name if twist)
└── monster_variants (5× goblin with different colors)

12. HUD — On-screen Variable Display

The HUD (Heads-Up Display) projects variables in real-time onto the game screen, creating visible and immersive progression mechanics.

12.1 Activation and Global Configuration

Access: ⚙️ TOOLS → HUD

12.2 Display Styles

12.3 Configuring HUD Variables

For each displayed variable:

Example: Complete Narrative RPG

Configured HUD variables:

Screen render: [💰 150] [❤️ 8] [🔮 25] [👑 Reputation: 12] [14]

12.4 Available Icons

Capsule offers 28 icons covering common uses:

Customization: Click the icon in configuration to open the selector.

12.5 Narrative Use Cases

Visual Novel with Relationship Management

HUD: [💕 Affection: 45] [🔥 Tension: 12]

Choice: "Compliment her dress"
→ Action: affection + 5
→ HUD updates: [💕 Affection: 50] in real-time

Survival Horror with Limited Resources

HUD: [🔋 Battery: 23%] [💊 Medkits: 1] [🗝️ Keys: 0]

Each exploration scene can modify these values.
The player constantly sees the fragility of their situation.

Mystery with Collected Clues

HUD: [📊 Clues: 3/7]

Variable clues incremented by triggers on hotspots.
Implicit objective: complete the collection.

13. CG Gallery — Unlockable Images and Videos

The CG Gallery manages illustrations and cinematics that the player unlocks by progressing, creating a persistent and motivating collection.

13.1 Gallery Architecture

13.2 Gallery Configuration

Access: ⚙️ TOOLS → CG Gallery

Adding an Item

For each item:

13.3 Unlock Mechanisms

Automatic Unlocking (Recommended)

The CG unlocks automatically when the player sees the image/video in normal gameplay.

Required configuration:

• Use exactly the same URL/file as scene background and in the gallery
• Capsule detects match and unlocks

Example: Ending Illustration

• Import ending_elara.webp into CG Gallery
• Title: "Promised Future"
• Category: "Endings"
• In the final scene ending_elara:
  • Background: ending_elara.webp (same file)
• When player reaches this scene:
  • Image displays normally
  • Capsule detects: "This image is in the gallery"
  • Automatic unlock + silent notification

Manual Unlocking (Advanced)

For secret CGs not displayed directly:

Trigger or Action:
- Type: Unlock CG
- Target: cg_secret_001

Result: Player receives the CG without having "seen" it normally.
Usage: Easter eggs, achievements, bonus content.

13.4 Player Experience

In Main Menu

GALLERY button appears automatically if:

• At least 1 CG defined in project
• At least 1 CG unlocked by player

Gallery Interface

13.5 Design Strategies

Narrative Structure by Collection

Videos in Gallery

Recommended specifications:

• Format: WebM (VP9) or MP4 (H.264)
• Resolution: 1920×1080
• Duration: 10-60 seconds
• Audio: Ogg Vorbis or AAC

Use Case: Ending Cinematics

Each main route unlocks a 30s video (stylized credits).

The gallery becomes a "cinematheque" of reached endings.

14. Timeline — Visual Story Map

The Timeline is a graphic representation of all your scenes and their connections, essential for visualizing complex narrative structure.

14.1 Timeline Interface

Access: ⚙️ TOOLS → Timeline

14.2 Visual Node Types

14.3 Navigation and Manipulation

14.4 Available Layouts

14.5 Reading Structure

Example: Problem Detection

You see a 🔴 red node (orphan) named secret_ending_good.

Investigation:

• Check choices — none point to secret_ending_good
• Check triggers — no goto to this scene
• Check global events — nothing either

Diagnosis: This scene exists but is inaccessible. Either:

• You forgot a connection (bug)
• It's intentional (future content, unimplemented secret)

Example: Flow Optimization

Timeline in Horizontal layout shows:

[start] → [intro] → [hub] ─┬→ [route_A] → [ending_A1]
                           ├→ [route_B] → [ending_B1]
                           └→ [route_C] → [ending_C1]

All routes converge from hub. Verify that hub indeed has the 3 corresponding choices.

14.6 Development Workflow

15. Global Search — Instant Project Search

Global Search allows instantly finding any content in all your scenes, critical for maintenance of large projects.

15.1 Activation

15.2 Search Interface

┌─────────────────────────────────────────┐
│  🔍 [Search in all scenes...      ]  ✕  │
├─────────────────────────────────────────┤
│  [📋 All] [💬 Dialogues] [🔀 Choices]   │
│  [📑 Scene IDs] [🧮 Variables] [🖼️ Media] │
├─────────────────────────────────────────┤
│  Results:                               │
│  • Scene: tavern_confrontation          │
│    Type: Dialogue                       │
│    "You owe me {gold} coins, stranger"  │
│                                         │
│  • Scene: market_haggle                 │
│    Type: Variable                       │
│    gold = gold - 20                     │
├─────────────────────────────────────────┤
│  2 results          Press Enter to go   │
└─────────────────────────────────────────┘

15.3 Search Filters

15.4 Results and Navigation

Each result displays:

• Scene: ID of scene containing match
• Type: Category of found content
• Context: Excerpt with highlighted term

Interaction:

• Click on a result → Open scene in editor
• Enter → Navigate to first result
• Esc → Close panel

15.5 Professional Use Cases

Variable Audit

Search: "reputation"
Filter: Variables

Results:
• Scene: palace_audience
  reputation = reputation + 5
  
• Scene: tavern_brawl  
  reputation = reputation - 10
  
• Scene: ending_check
  Condition: reputation >= 50

Analysis: The variable is properly defined and used consistently.

Post-Revision Correction

Problem: Character was named "Marcus", now "Markus"

Search: "Marcus"
Filter: Dialogues

Results: 12 occurrences in 8 scenes

Action: Click each result → manual replacement or
         verify that {actor:marcus} is used correctly

Asset Verification

Search: "tavern_background.webp"
Filter: Media

Results:
• Scene: tavern_intro (Background)
• Scene: tavern_night (Background)  
• Scene: tavern_fight (Background)
• CG Gallery: "Tavern Atmosphere"

Analysis: Image used 3 times + in gallery. 
         Possible optimization: different day/night versions?

16. Stats — Monitoring Project Health and Size

The Stats panel monitors in real-time the technical health and size of your project, preventing issues before export.

16.1 Dashboard

16.2 Visual Distribution

Proportional colored bar:

• 🟢 Green (Images)
• 🔵 Blue (Music)
• 🟠 Orange (SFX)
• 🟣 Purple (Videos)

Immediate identification of dominant asset type.

16.3 Asset Alerts

Automatic detection of large files:

Alert Example:

⚠️ orchestral_theme.mp3 — 8.5 MB

Advice: Convert to OGG 64kbps → ~2 MB without perceptible audible loss

16.4 Project Health

Automatic software validation:

16.5 Quality Workflow

17. CONFIG — Global Project Configuration

The CONFIG panel centralizes all settings defining the identity and global behavior of your visual novel.

17.1 Access and Architecture

Access: 🏠 Button (house) in header or ⚙️ TOOLS → Config navigation.

17.2 Game Title

Example: Title Evolution

• Prototype phase: "MY GAME"
• Production phase: "Chronicles of Aetheria: The Hollow Crown"

The title can be modified at any time without impacting saves.

17.3 Languages — Multilingual Management

Capsule supports 5 native languages with adapted dialogue structure.

Available Languages

Configuration

Format: codes separated by commas, no spaces

Configuration: en,fr,es

Result: The game offers three languages in Options.

Impact on Dialogue Structure

Each dialogue line becomes a multilingual object:

Internal structure:
{
  "en": "Hello, traveler.",
  "fr": "Bonjour, voyageur.",
  "es": "Hola, viajero."
}

In the editor: Additional fields appear for each configured language.

Concrete Example: Trilingual Configuration

CONFIG → Languages: en,fr,de

Dialogue Editor displays:

[EN] "Welcome to the tavern."
[FR] "Bienvenue à la taverne."
[DE] "Willkommen in der Taverne."

The player selects language in Options → all text switches.

Default Language

The first language in list is default:

• At first launch
• If player language is unavailable
• For untranslated dialogues (fallback)

17.4 Menu Background

Static Image

Example: Epic Fantasy

• Image: menu_hero_standing.webp
• Hero silhouetted against sunset
• Warm tone, promise of adventure
• Title logo overlaid

Animated Video

Optimal Specs:

• Duration: 10-30 seconds (smooth loop)
• Codec: H.264 (MP4) or VP9 (WebM)
• Audio: None (music managed separately)
• Size: < 5MB for fast loading

Example: Sci-Fi

• Video: menu_hyperspace_loop.mp4
• Passing stars, warp effect
• Perfectly seamless loop
• Creates illusion of moving ship

17.5 Menu Music

Behavior:

• Automatic playback after first click (browser constraint)
• Infinite loop while menu is displayed
• Fade on scene change (crossfade if different music)
• Immediate stop on NEW GAME

Example: Memorable Theme

• Track: main_theme.ogg
• 60 seconds, A-B-A' structure
• Recognizable from first notes
• Orchestral reprise in key game moments

17.6 Developer Mode

Enables a complete debug panel accessible in-game.

Activation

CONFIG → Developer Mode → ☑️ Enable Dev Mode
The button 🛠️ appears in top-right corner in-game.

Dev Panel Interface

┌─────────────────────────────┐
│ 🛠️ DEV MODE              ✕  │
├─────────────────────────────┤
│ CURRENT SCENE: forest_ambush │
│ LANGUAGE: EN                │
├─────────────────────────────┤
│ ⚙️ COUNTERS                 │
│ Redirects: 3/100            │
│ Logic Depth: 0/50           │
├─────────────────────────────┤
│ 📊 VARIABLES [🔍 Filter]    │
│ gold        │ 150           │
│ health      │ 8      [edit] │
│ hasKey      │ true   [edit] │
├─────────────────────────────┤
│ 🌐 GLOBAL EVENTS            │
│ #1: reputation >= 50 │ ✓   │
│ #2: day > 7          │ ○   │
├─────────────────────────────┤
│ JUMP TO SCENE [dropdown ▼]  │
├─────────────────────────────┤
│ ⏪ ROLLBACK: 12 snapshots   │
│ [-1] [-5] [📋 List]         │
├─────────────────────────────┤
│ 📋 EVENT LOG                │
│ 14:32:05 🎬 Enter: start    │
│ 14:32:18 📊 gold: 0 → 150   │
│ 14:32:45 ⚡ Trigger fired   │
└─────────────────────────────┘

Rollback system (v1.6.3+)

Automatic saves at each narrative scene:

Each snapshot contains:

• Scene and dialogue index
• All variable values
• Full inventory
• Global events triggered

Example: Narrative Branch Test

You test a romance. At scene 45, you realize a choice at scene 12 blocked the route.

Action: Rollback → select snapshot scene 11 → modify variable affection_elara → re-test.

Time saved: minutes instead of replaying from start.

State Export (Debug)

Button 📋 COPY GAME STATE copies to clipboard:

{
  "currentScene": "palace_confrontation",
  "textIndex": 2,
  "variables": {
    "gold": 150,
    "reputation": 45,
    "hasRoyalSeal": true
  },
  "inventory": {
    "healing_potion": 3,
    "ancient_key": 1
  },
  "triggeredEvents": [0, 3],
  "timestamp": "2024-01-15T14:32:18Z"
}

Usage: Paste into bug report, share with team, or manually restore.

17.7 Auto-Start

Skips title screen to start immediately.

Use Case: Multi-chapters

Project structure:
├── chapter1.html (Auto-Start: OFF)
├── chapter2.html (Auto-Start: ON)
├── chapter3.html (Auto-Start: ON)
└── epilogue.html (Auto-Start: ON)

Player Flow:
chapter1.html → menu → NEW GAME → play
Final scene: Jump to HTML File: chapter2.html
chapter2.html starts immediately (no menu)
Variables transferred automatically via localStorage

Example: Saga in 3 Acts

Act I: Introduction, fundamental choices, cliffhanger

• Export: aetheria_act1.html (Auto-Start: OFF)

Act II: Consequences, new alliances, revelation

• Export: aetheria_act2.html (Auto-Start: ON)
• Detection: if Act I variables absent, message "Please play Act I first"

Act III: Climax, multiple endings, epilogue

• Export: aetheria_act3.html (Auto-Start: ON)

Audio Handling in Auto-Start

Browsers block audio autoplay. Capsule handles this:

Auto-Start Behavior:
1. start scene displays immediately
2. Music/SFX waiting for first click
3. First click anywhere → unlock audio
4. Normal playback thereafter

18. Integration Example — Complete Project

To illustrate the interconnection of all features, here is the complete configuration of a professional visual novel.

18.1 GLOBAL CONFIGURATION

┌─────────────────────────────────────────┐
│  🏠 HOME SCREEN CONFIGURATION           │
├─────────────────────────────────────────┤
│  Game Title: "Chronicles of Aetheria"   │
│                                         │
│  Languages: en,fr,es                    │
│                                         │
│  Menu Background:                       │
│  ☑️ Video → menu_loop.mp4 (WebM, 8MB)   │
│                                         │
│  Menu Music:                            │
│  ☑️ main_theme.ogg (128kbps, loop 60s)  │
│                                         │
│  Developer Mode:                        │
│  ☑️ Enable Dev Mode                     │
│                                         │
│  Auto-Start:                            │
│  ☐ Disabled (main menu active)          │
└─────────────────────────────────────────┘

18.2 CONFIGURED ACTORS

18.3 UI CUSTOM

Default Appearance:

• Font: 'Palatino Linotype', serif
• Shape: shape-gem
• Colors: gold #D4AF37, brown #3E2723, cream #FFF8E1

18.4 ENABLED HUD

Position: Top Left
Style: Compact
Background: Dark

Displayed Variables:
┌─────────────────┐
│ 💰 150 ❤️ 8 🔮 25 │
└─────────────────┘

18.5 CG GALLERY

18.6 NARRATIVE FLOW (Timeline)

[start] → [intro] → [village_hub] ──┬──→ [lyra_route] ──→ [lyra_ending]
                                    ├──→ [kael_route] ──→ [kael_ending]
                                    └──→ [archon_early] ──→ [bad_ending_1]

[village_hub] requires: day < 7
If day >= 7: force [archon_confrontation]

18.7 QUALITY CONTROL POINTS

19. Advanced Mechanics — Design Recipes

This section presents complete design patterns, ready to implement, for sophisticated game mechanics.

19.1 Complete D&D Dice System (Roll + Add)

Capsule v1.8.0 introduces the Roll + Add action for skill checks Dungeons & Dragons style.

Pattern: Strength Check with Bonus

Context: Player attempts to lift a heavy door. Result = d20 + Strength modifier.

Configuration in 3 triggers:

Detail of Roll + Add Action:

Action Type: Roll + Add
Dice: min 1, max 20
Source Variable: strengthMod (character value, ex: +3)
Target Variable: result

Numerical Example:

• strengthMod = 3 (strong hero)
• Roll: 14 on d20
• Calculation: 14 + 3 = 17
• result = 17
• Trigger 2 fires (17 >= 15) → door_opened

Variant: Degrees of Success

Implementation: 4 triggers in cascade

Trigger 1: roll → result = d20 + mod
Trigger 2: if result >= 20 → door_perfect
Trigger 3: if result >= 15 → door_opened  
Trigger 4: if result >= 10 → door_partial
Trigger 5: (no condition) → door_stuck [fallback]

19.2 Turn-Based Combat System

Complete Architecture

Phase 1: Initiative (Roll + Add)

Scene combat_init (Logic):

Routing Triggers:

Trigger: player_first
  IF: playerInit >= enemyInit
  THEN: Go to combat_player

Trigger: enemy_first  
  IF: playerInit < enemyInit
  THEN: Go to combat_enemy

Phase 2: Player Turn (Choice + Actions)

Scene combat_player:

Consequence: All choices lead to combat_check_end

Phase 3: End Combat Check

Scene combat_check_end (Logic):

Trigger: victory
  IF: enemyHP <= 0
  THEN: Go to combat_end_victory

Trigger: defeat
  IF: playerHP <= 0
  THEN: Go to combat_end_defeat

Trigger: continue_player
  IF: playerInit >= enemyInit AND lastActor = "enemy"
  THEN: Go to combat_player

Trigger: continue_enemy
  IF: enemyInit > playerInit AND lastActor = "player"
  THEN: Go to combat_enemy

Phase 4: Iteration

The logic combat_check_end redirects to:

• End if victory/defeat condition met
• Next turn if combat continues

Timeline Visualization:

[combat_init] → [combat_player] ↔ [combat_enemy]
       ↓              ↓                  ↓
[combat_end_victory] ← [combat_check_end] → [combat_end_defeat]

19.3 Quest System with States

Pattern: 3-Step Quest

Implementation with Conditional Triggers:

In village_hub, an NPC changes dialogue based on state:

Trigger: quest_not_started
  IF: quest_blacksmith = 0 AND hasMetBlacksmith = false
  THEN: Go to blacksmith_intro

Trigger: quest_active  
  IF: quest_blacksmith = 1
  THEN: Go to blacksmith_reminder

Trigger: quest_ready
  IF: quest_blacksmith = 2
  THEN: Go to blacksmith_almost

Trigger: quest_done
  IF: quest_blacksmith = 3
  THEN: Go to blacksmith_thanks

19.4 Faction Reputation System

Multi-Faction Architecture

Example of Multi-Impact Choice:

Choice: "Turn the thief over to the Guild"
- Action: rep_guild + 5
- Action: rep_cult - 3 (thief was an informant)
- Action: rep_guard + 2 (justice served)

Faction Ending Condition:

Scene: ending_faction_check (Logic)

Trigger: guild_ending
  IF: rep_guild >= 25 AND rep_cult < 0
  THEN: Go to ending_guild_master

Trigger: cult_ending
  IF: rep_cult >= 25
  THEN: Go to ending_cult_leader

Trigger: balanced_ending
  IF: rep_guild >= 10 AND rep_cult >= 10
  THEN: Go to ending_peacemaker

20. Professional Production Tips

20.1 Development Workflows

"Prototype → Polish" Method

Parallel Development

Synchronization: Integrator imports assets progressively, tests immediately in Capsule.

20.2 Asset Optimization

Images — Recommended Pipeline

Source (PSD/PNG) → Export 1920×1080 → WebP Conversion → Capsule Import
         ↓
    [Quality 90%, effort 6]
         ↓
    Typical size: 200-500 KB vs 2-5 MB PNG

Audio — Target Specifications

Video — Optimal Encoding

Input: 1920×1080 30fps
↓
Codec: VP9 (WebM) or H.264 (MP4)
Bitrate: 2-5 Mbps
Audio: AAC 128kbps or Ogg Vorbis
↓
Target: < 10 MB for 30 seconds

20.3 Efficient Debugging

Test Logbook

Create a debug_log variable (text):

Action in key scenes:
- debug_log = debug_log + "[Scene: " + currentScene + ", Vars: " + gold + "/" + health + "]\n"
Export via Dev Mode → Copy Game State to trace paths.

Systematic Branch Testing

20.4 Save Patterns

Implicit Checkpoint System

Automatic Save Scenes (invisible):

[chapter1_checkpoint] (Logic)
- Action: save_slot = "auto_ch1"
- Next: chapter1_continues

Detection on load:
- If save_slot starts with "auto_" → display "Continue Chapter X"

Persistent Meta-Progression

Variables stored outside scenario save (via global event):

20.5 Advanced Internationalization

Text Length Management

Test: Enable all languages, visually verify text fits in dialogue boxes.

Cultural Content

Implementation of Conditional Content per Language:

Scene: joke_scene

Dialogue EN: "That's what she said."
Dialogue FR: "C'est pas faux."
Dialogue ES: "Como dicen por ahí."

Alternative: Create a logic scene `joke_router`:
- Trigger: if lang = "en" → joke_english
- Trigger: if lang = "fr" → joke_french
- Trigger: if lang = "es" → joke_spanish

20.6 Security and Robustness

Player Input Validation (Text Input)

Implicit Sanitization: Capsule automatically escapes dangerous HTML characters (<, >, &, ", ') in text inputs.

Anti-Cheat Protection

20.7 Performance and Scale

Scene Limit

Chaptering Strategy:

Project "War and Peace" (2000+ scenes):

chapter1.html: Scenes 1-400, Prologue → Act I
chapter2.html: Scenes 401-800, Act II
chapter3.html: Scenes 801-1200, Act III
chapter4.html: Scenes 1201-1600, Act IV
chapter5.html: Scenes 1601-2000, Act V + Epilogue

Key variables transferred: rep_guild, rep_cult, heroName, gold, level

Load Time Optimization

21. Interactive Scenario Recipes

21.1 Emotional Feedback Loop

21.2 The 3-7-10 Rule

21.3 Narrative Tension Management

Ideal Tension Curve:

Tension
  ↑
  │    ╭─╮      ╭──╮        ╭──╮
  │   ╱   ╲    ╱    ╲      ╱    ╲_____
  │  ╱     ╲__╱      ╲____╱          ╲___
  │ ╱                                    ╲___
  │╱                                          ╲___
  └────────────────────────────────────────────────→ Time
    Intro  Conflict1 Conflict2  Climax  Resolution

Choice Points: ↓ (moderate tension, possible decision)
               ↓ (max tension, forced decision)

Capsule Implementation:

22. Integration and Deployment

22.1 Pre-Export Checklist

22.2 Distribution Platforms

22.3 Post-Launch

Appendices

A. Keyboard Shortcuts

B. Quick Tag Reference

C. Engine Evolution

23. Capsule Glossary

24. Resources and Community

24.1 Royalty-Free Assets

24.2 Complementary Tools