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 and sprite animations
• 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
• DSL Script — Import a CapsuleScript (.cvl) file directly into your project

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

Typewriter Effect

Dialogue text appears character by character, simulating live speech. The player controls the reading pace:

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

The dice() Function

The dice(min, max) function generates a random integer between min and max (inclusive). It can be used in Set Variable actions to build any random system:

# Roll a standard 6-sided die
randomRoll = dice(1, 6)

# Roll a d20 (tabletop RPG standard)
d20result = dice(1, 20)

# Simulate a coin flip (0 or 1)
coinFlip = dice(0, 1)

# Random event 1-in-4 chance (equals 1 out of 4 values)
chanceRoll = dice(1, 4)
# Then: trigger IF chanceRoll = 1 → rare_event

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.

5.8 Global Events — Persistent Cross-Scene Triggers

Global Events are triggers that watch for a condition across every scene in your entire game. Unlike scene-level triggers that only fire when their specific scene is loaded, a Global Event continuously evaluates its condition whenever the game state changes — regardless of which scene the player is currently in.

Access: ⚙️ TOOLS → Events

5.8.1 Configuration

5.8.2 Evaluation Timing

Global Events are evaluated:

• At every scene entry
• After any variable modification (triggered by scene actions, choices, or triggers)
• After inventory changes

Evaluation is prioritized — if multiple Global Events trigger simultaneously, they are evaluated in order from top to bottom in the Events panel. The first redirect wins.

5.8.3 Essential Use Cases

Use Case 1: Death / Game Over System

Event ID:   check_death
Condition:  health <= 0
Action:     Go to Scene: game_over
Fire Once:  No (re-evaluates every scene — player may recover health)

Effect: If any action anywhere in the game reduces health to 0 or below,
        the player is redirected to the game_over scene immediately.
        No need to check health manually in every scene.

Use Case 2: Reputation Milestone Unlock

Event ID:   reputation_hero
Condition:  reputation >= 100
Action:     Go to Scene: hero_title_cutscene
Fire Once:  Yes (plays the cutscene once, then never again)

Effect: Wherever the player is when reputation crosses 100, they are
        taken to a special cutscene and awarded the Hero title.
        Fire Once prevents it from interrupting repeatedly.

Use Case 3: Day Limit — Urgency Mechanic

Event ID:   day_limit_reached
Condition:  day >= 7
Action:     Go to Scene: archon_confrontation_forced
Fire Once:  Yes

Effect: If the player spends too many in-game days exploring without
        confronting the antagonist, the story is forced forward.
        Creates urgency — "the world does not wait for you."

Use Case 4: CG Gallery Auto-Unlock

Event ID:   unlock_secret_cg
Condition:  foundSecretRoom = true
Action:     Set Variable: cg_secret_unlocked = true
Fire Once:  Yes

Effect: The moment the player sets foundSecretRoom to true (anywhere),
        the secret CG is silently unlocked in the gallery.

Use Case 5: Sanity / Horror Meter

Event ID:   sanity_collapse
Condition:  sanity <= 20
Action:     Go to Scene: hallucination_sequence
Fire Once:  No

Effect: Whenever sanity drops to 20 or below, the player experiences
        a hallucination. Because Fire Once is off, it can trigger
        repeatedly — reinforcing the horror of repeated trauma.
        (Add a cooldown variable to limit frequency if needed.)

5.8.4 Disabling Events in Safe Zones

Some events should not fire during tutorials, menus, or special sequences. Use a guard variable:

Event:      check_death
Condition:  health <= 0 AND safeMode = false

Add a Logic Scene before tutorial:
  Action: Set safeMode = true

Add a Logic Scene when tutorial ends:
  Action: Set safeMode = false

Effect: The death system is fully suspended during the tutorial,
        then automatically reactivates when gameplay begins.

5.8.5 Global Events vs Scene Triggers — When to Use Which

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.

6.6 Cinematic Camera System (v1.9.0)

The Cinematic Camera System adds programmatic movement to static scene backgrounds, creating the illusion of a living, breathing world without requiring video assets. Applied per-scene, it transforms a still image into a cinematic experience through smooth zoom and pan effects rendered entirely in CSS — no performance cost, no file size increase.

6.6.1 How It Works

When a scene is displayed, the camera effect animates the background layer independently of sprites, dialogue, and UI elements. The background image is scaled slightly beyond the viewport to create movement room, then glides according to the chosen mode. Characters and dialogue boxes remain perfectly stable — only the background moves.

6.6.2 Configuration

In the scene editor, in the Visual & Sound section, open the 🎥 Camera panel and configure:

• Camera Mode: Dropdown selector for the type of movement
• Intensity: How pronounced the effect is (0.1 = subtle, 1.0 = dramatic)
• Duration: Length in seconds of one complete animation cycle

6.6.3 Available Camera Modes

6.6.4 Parameters

6.6.5 Practical Examples

Example 1: Epic Opening Scene — Mountain Panorama

Background:   mountain_dawn_wide.webp (2560×1080)
Camera Mode:  Ken Burns
Intensity:    0.2 (subtle)
Duration:     20s

Result: As the opening narration plays, the camera slowly pans
across the mountain range and gently zooms in. The scene feels
vast, cinematic, and alive — without any video asset.

Example 2: Horror Scene — Abandoned Corridor

Background:   asylum_corridor.webp
Camera Mode:  Zoom In
Intensity:    0.5
Duration:     8s

Effect: The perspective slowly closes in. As dialogue unfolds,
the claustrophobic zoom makes the player feel the walls
are moving. Combined with effect: fog — extremely effective.

Example 3: Dream Sequence

Background:   dreamscape_abstract.webp
Camera Mode:  Drift
Intensity:    0.4
Effect:       floating_dust
Filter:       sepia

Effect: Random micro-movements combined with floating particles
and warm sepia tones signal an altered state of consciousness.

Example 4: Tense Confrontation — Throne Room

Background:   throne_room.webp
Camera Mode:  Breathe
Intensity:    0.3
Duration:     4s (fast cycle = rapid heartbeat feel)

Effect: The subtle pulsing zoom mimics a heartbeat under stress.
It amplifies the tension of dialogue without distracting from it.

Example 5: Travel Montage

Sequence of 3 scenes, each with:
Camera Mode:  Pan Left
Intensity:    0.6
Duration:     6s
Transition:   crossfade

Effect: Characters appear stationary while backgrounds drift
leftward across scenes — convincingly simulates movement
through different landscapes.

6.6.6 Synergy with Atmospheric Effects

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

Native App Distribution

To release your game as a standalone Windows desktop app (.exe) or Android app (.apk), use the companion tools bundled with Capsule:

• HTML2EXE → converts any HTML export (including multi-chapter) into a .exe for Windows. See section 8.4 for full guide.
• HTML2APK → converts any HTML export (including multi-chapter) into an .apk for Android. See section 8.5 for full guide.

Direct Sharing

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

8.4 HTML2EXE — Native Desktop App (Windows)

Capsule HTML2EXE converts your exported HTML game file into a native .exe Windows desktop application — in exactly one click. The resulting executable is a fully self-contained program: no browser required, no internet connection, no external dependencies.

HTML2EXE supports multi-chapter projects: bundle all your chapter HTML files together into a single installer that handles chapter transitions automatically.

8.4.1 System Requirements

8.4.2 Conversion Workflow

1. Export your completed game from Capsule Studio (💾 EXPORT → HTML file)
2. Open Capsule HTML2EXE
3. Click Add File(s) and select your HTML file(s)
   • Single chapter: add one file
   • Multi-chapter saga: add all chapter files in order (chapter1.html, chapter2.html...)
4. Configure game info: Title, Window Icon (.ico), Window Size
5. Click Build .EXE
6. Done — a .exe file is generated in your output folder

8.4.3 Multi-Chapter Support

When bundling multiple chapters:

• All chapter HTML files are embedded inside the .exe
• Chapter transitions (Jump to HTML File) resolve internally — no external files needed
• Save data and variable transfers between chapters work identically to the browser version
• The player sees a seamless experience — no file system exposure

Example multi-chapter project:
aetheria_chapter1.html    ← Add all three
aetheria_chapter2.html
aetheria_chapter3.html
        ↓
HTML2EXE (1 click)
        ↓
Chronicles_of_Aetheria.exe   ← Single distributable file
                              ← Contains all 3 chapters internally

8.4.4 Distribution via .EXE

8.5 HTML2APK — Native Android App

Capsule HTML2APK converts your exported HTML game into an .apk Android package — in exactly one click. The resulting APK installs directly on any Android device (4.4+) and runs as a native app with its own home screen icon, full-screen display, and offline capability. No Google Play account required for direct distribution.

HTML2APK also supports multi-chapter projects: all chapters are bundled into a single APK, with chapter transitions handled internally.

8.5.1 System Requirements

8.5.2 Conversion Workflow

1. Export your completed game from Capsule Studio (💾 EXPORT → HTML file)
2. Open Capsule HTML2APK
3. Click Add File(s) and select your HTML file(s)
   • Single chapter: add one file
   • Multi-chapter saga: add all chapter files in order
4. Configure app info: App Name, Package ID, App Icon (512×512 PNG), Splash Screen (optional)
5. Click Build .APK
6. Done — an .apk file is generated, ready to install or publish

8.5.3 Multi-Chapter Support

The multi-chapter behavior is identical to HTML2EXE:

aetheria_chapter1.html
aetheria_chapter2.html
aetheria_chapter3.html
        ↓
HTML2APK (1 click)
        ↓
chronicles_of_aetheria_v1.0.apk   ← All 3 chapters bundled
                                   ← Transitions work internally
                                   ← Save data transfers automatically

8.5.4 Package ID Convention

The Package ID uniquely identifies your app on the Android ecosystem. Use the reverse domain format:

Format:    com.yourname.gamename
Example:   com.lyrastudios.aetheria
Example:   io.itch.yourprofile.mygame
Example:   com.github.username.projectname

Rules:
  - Lowercase only
  - Only letters, digits, and dots
  - No spaces or special characters
  - Must be globally unique if publishing to Google Play

8.5.5 Distribution via .APK

8.5.6 Mobile Optimization for APK

Before converting to APK, optimize your project specifically for mobile:

8.5.7 HTML → EXE / APK Comparison

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

Q: My Global Event fires on every scene, not just once

Enable the Fire Once option on the event. This causes the event to disable itself after its first trigger. Without it, the event re-evaluates (and potentially re-fires) every scene.

Q: A Global Event is firing at the wrong moment and interrupting important scenes

Add a guard variable (e.g., safeMode = true) to your event condition: health <= 0 AND safeMode = false. Set safeMode = true before scenes you want to protect, and safeMode = false when you want the event to be active again.

Q: HTML2APK shows a "Install Unknown Sources" warning on Android

This is a standard Android security prompt for apps not installed from the Play Store. The player must go to Android Settings → Security → "Install unknown apps" and enable it for their file manager or browser. Include these instructions in your release notes for sideloaded APK distribution.

Q: My .exe shows a Windows SmartScreen warning

This happens because your executable is not signed with a commercial code-signing certificate. Players can click "More info → Run anyway" to proceed. For commercial releases, consider purchasing a code-signing certificate (~$200–$500/year) to eliminate this warning entirely.

Q: Chapter transitions don't work in the .exe or .apk

Make sure you added all chapter HTML files to HTML2EXE/HTML2APK, not just chapter 1. When bundled together, internal chapter transitions resolve automatically. If you only added one file, the app cannot find the other chapters.

Q: Can I publish my Capsule game on Steam?

Yes. Use HTML2EXE to create a .exe, then package it through Steamworks. Capsule games function as any other PC game on Steam. You can additionally integrate Steam achievements by calling the Steam overlay API from a custom HTML wrapper, though this requires technical knowledge. The simplest approach is to release the .exe as-is — Steam handles all distribution and DRM.

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:

Positioning Guide

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)

11.6 Sprite Sheet Character Animation (v1.9.0)

Sprite Sheet Animation brings characters to life with frame-by-frame animation, directly within Capsule's actor system. Instead of a static portrait, an expression references a sprite sheet — a single image containing all animation frames arranged in a regular grid. Capsule reads the grid configuration and cycles through frames, producing smooth 2D character animation with zero additional complexity in your scene setup.

11.6.1 Preparing Your Sprite Sheet

Before importing into Capsule, your sprite sheet must follow these rules:

• All frames must have identical dimensions. If each frame is 256×512 px and you have 8 frames in 4 columns × 2 rows, the total image must be exactly 1024×1024 px.
• Frames are read left-to-right, top-to-bottom. Frame 1 is top-left; the last frame is bottom-right.
• PNG with transparent background is strongly recommended for character sprites — it allows proper layering over scene backgrounds.
• Avoid heavy lossy compression. JPEG artifacts are amplified when cycling through frames. Use PNG or WEBP at 90%+ quality.
• Empty padding cells are allowed. If your 4×2 grid only has 7 meaningful frames, set Frames to 7 — Capsule will not display the 8th empty cell.

Sprite Sheet Anatomy — Visual Reference:

Example: 4 columns × 2 rows = 8 cells
Each frame: 256 × 512 px
Total image: 1024 × 1024 px

┌──────────┬──────────┬──────────┬──────────┐
│ Frame 1  │ Frame 2  │ Frame 3  │ Frame 4  │  ← Row 1
├──────────┼──────────┼──────────┼──────────┤
│ Frame 5  │ Frame 6  │ Frame 7  │ (empty)  │  ← Row 2
└──────────┴──────────┴──────────┴──────────┘

Playback order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → (loop)
Frames = 7 (the empty 8th cell is automatically skipped)

11.6.2 Activating Animation on an Expression

Animation is configured per-expression inside the Actor panel:

1. Open ⚙️ TOOLS → Actors and select your actor
2. Find the expression you want to animate (e.g., default, happy)
3. Import your sprite sheet image as the expression's source (📂 Choose File)
4. Click 🎬 Configure Animation to expand the Sprite Sheet panel
5. Set grid parameters (Columns, Rows, Frames, Frame Width, Frame Height)
6. Choose an Animation Mode
7. Set playback speed (FPS preset or custom)
8. Observe the live preview in the right panel

11.6.3 Grid Configuration Parameters

How to calculate Frame Width and Frame Height:

Frame Width  = Total Image Width  ÷ Columns
Frame Height = Total Image Height ÷ Rows

Example: 1024 × 1024 image, 4 columns, 2 rows
Frame Width  = 1024 ÷ 4 = 256 px
Frame Height = 1024 ÷ 2 = 512 px

11.6.4 Animation Modes

11.6.5 Playback Speed

11.6.6 Complete Setup Example: Animated Elara

Goal: Elara's happy expression shows her hair gently swaying.

Step 1 — Prepare the sprite sheet:

elara_happy_anim.png
6 frames of hair movement: 3 columns × 2 rows
Each frame: 256 × 512 px
Total image: 768 × 1024 px

Step 2 — Configure in Actor panel:

Step 3 — Result:
In any scene where Elara appears with expression happy, her portrait is smoothly animated. No per-scene configuration is required. The animation runs as a background process, independent of dialogue flow.

11.6.7 Animation Design Recipes

Recipe 1: Breathing Idle (any character)

8–12 frames of subtle chest and shoulder rise/fall
Mode:  🔄 Continuous Loop
FPS:   3–4 (natural breathing rhythm ~15 cycles/min)
Apply to: "default" and "idle" expressions

Effect: Character feels present and alive even during long
        silent narration sections. Transforms your VN from
        a slideshow into a living world.

Recipe 2: Natural Eye Blink

5 frames: fully-open → half-closed → closed → half-open → open
Mode:  🔄 Continuous Loop
FPS:   8 (blink itself is fast)

Tip: Add 3–4 extra "fully open" frames between blinks to
     create a natural pause. Sequence example:
     open, open, open, open, half, closed, half, open, open...
     This produces a blink every ~1.3 seconds at 6 fps.

Recipe 3: Attack / Combat Action

12–16 frames of full attack animation (windup → strike → recovery)
Mode:  ⚡ Once (action)
FPS:   12–24 (fast, impactful)
Apply to: "battle" or "attack" expression

Effect: Animation plays at full speed on scene entry, then
        holds on the final pose frame. The character looks
        powerful and decisive. Does not loop or repeat.

Recipe 4: Talking Mouth (Lip Sync Approximation)

4–6 frames of different mouth positions (open, half, closed, wide)
Mode:  🗣️ Talk (pause when done)
FPS:   10–12

Effect: Rapidly cycles through mouth positions while the
        typewriter text effect is active, then holds on
        the neutral closed-mouth frame when the line ends.
        Creates a convincing speech impression.

Recipe 5: Looping Magical Aura

8 frames of particle/glow effect around character
Mode:  🔄 Continuous Loop
FPS:   6–8
Apply to: "magic" or "charged" expression

Effect: Magic sparkles or energy flows continuously around
        the character as a visual status indicator.
        Highly effective for mage characters or powered-up states.

11.6.8 Recommended Tools for Creating Sprite Sheets

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.0 Capsule System Requirements

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 Multi-Platform Release Checklist

When preparing a release across HTML, EXE, and APK simultaneously:

20.6 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.7 Security and Robustness

Player Input Validation (Text Input)

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

Anti-Cheat Protection

20.8 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

23. CapsuleScript (.cvl) — The Domain-Specific Language

CapsuleScript is the native scripting language of Capsule VN Engine, designed specifically for visual novel authoring. A .cvl file is a plain-text script that encodes your entire visual novel — scenes, dialogues, actors, variables, choices, triggers, and more — in a human-readable format. You write your story in a text editor, then import it into Capsule with a single click.

CapsuleScript is not a programming language. You do not need to know how to code. It is a structured notation — like writing a screenplay with a fixed formatting convention — that Capsule's parser translates directly into a playable game.

23.1 Why Use CapsuleScript?

23.2 Importing a .cvl File

There are two ways to import CapsuleScript into your project:

• Via Tools: ⚙️ TOOLS → DSL Script → 📂 Choose File → select your .cvl file → click Import
• Via drag and drop: Drag any .cvl file directly onto the Capsule studio window

The parser reads the file and creates all declared scenes, variables, actors, and configuration in your project. Existing scenes with matching IDs are merged (their content is updated). New scene IDs are added to the list.

23.3 File Structure Overview

A .cvl file is organized into blocks. Each block starts with a keyword on its own line and ends when the next block begins or the file ends. Blocks can appear in any order. Here is the top-level anatomy:

# CapsuleScript v1.9
# Lines starting with # are comments — ignored by the parser

CONFIG
  title: "My Visual Novel"
  languages: en,fr

VARIABLE name type default
  gold       number  0
  heroName   text    "Alex"
  hasKey     bool    false

ACTOR id
  name: "Display Name"
  color: #hexcolor
  sprite expression: url_or_base64

SCENE scene_id
  bg: background_url
  music: music_url
  # ... scene content ...

CHOICES
  -> "Button text" scene_id
  -> "Another option" other_scene_id

23.4 Comments

Lines starting with # are comments. They are completely ignored by the parser and can appear anywhere.

# This is a comment — write notes for yourself here
SCENE tavern_intro
  # TODO: add background image later
  bg: placeholder.webp
  text: "The tavern is dimly lit." # inline comments are also supported

23.5 CONFIG Block

The CONFIG block defines global project settings. It maps directly to the CONFIG panel in the visual editor.

CONFIG
  title: "Chronicles of Aetheria"
  languages: en,fr,es
  autostart: false
  devmode: true
  menubg: menu_loop.mp4
  menumusic: main_theme.ogg

23.6 VARIABLE Block

Declares all project variables. Each line after VARIABLE declares one variable: name type default_value.

VARIABLE name type default
  gold         number   0
  heroName     text     "Alex"
  hasKey       bool     false
  reputation   number   50
  side         text     "neutral"
  questDone    bool     false

23.7 ACTOR Block

Declares a reusable character. One ACTOR block per character.

ACTOR elara
  name: "Elara"
  color: #D4AF37
  sprite default: elara_neutral.webp
  sprite happy: elara_smile.webp
  sprite sad: elara_tears.webp
  sprite determined: elara_fight.webp
  sprite surprised: elara_shock.webp

The actor ID (here elara) is the technical reference used in scene dialogue. The first sprite line defines the default expression — always include it.

23.8 SCENE Block — The Core

The SCENE block defines a single scene. The ID follows directly after the keyword: SCENE scene_id. The scene ID must be lowercase with no spaces (use underscores).

23.8.1 Scene Visual & Sound Properties

SCENE forest_path
  bg: forest_morning.webp
  music: ambient_birds.ogg
  sfx: leaves_rustle.ogg
  filter: sepia
  effect: floating_dust
  overlay: light_rays.webp
  transition: crossfade
  camera: ken_burns 0.2 15

23.8.2 Characters in a Scene

Place characters in a scene with char: lines:

SCENE village_morning
  bg: village_square.webp
  char: elara default left
  char: kael smirk right
  char: merchant default center

Syntax: char: actorID expression position

To change an actor's expression mid-scene (between dialogue lines), use expr::

SCENE confrontation
  char: elara default left
  char: kael default right
  say elara: "I trusted you."
  expr kael: angry         # Kael's expression switches to angry
  say kael: "You were naive to."
  expr elara: sad
  say elara: "..."

23.8.3 Dialogue Lines

Dialogue is written with say followed by the speaker ID and the line text:

say elara: "The forest path is clear today."
say kael: "Don't be fooled. Something feels wrong."
say: "A distant howl echoes through the trees."  # No speaker = narration

The speaker field is optional. Omitting it produces narration (no name box displayed).

Multilingual dialogue: When multiple languages are configured, use | to separate translations in order:

# CONFIG languages: en,fr,es
say elara: "The path is clear." | "Le chemin est dégagé." | "El camino está despejado."

Text formatting tags work identically inside dialogue:

say kael: "[b]Run![/b] The [shake]bridge[/shake] is collapsing!"
say: "You have [rainbow]{gold}[/rainbow] gold coins remaining."

23.8.4 Choices

Choices are declared with -> lines after a CHOICES keyword, or inline within a scene using the shorthand choice:.

Method 1 — Inline CHOICES block within a SCENE:

SCENE crossroads
  bg: crossroads.webp
  say: "The road forks ahead."
  CHOICES
    -> "Take the mountain pass"  mountain_pass
    -> "Follow the river road"   river_road
    -> "Camp here for the night" camp_scene

Method 2 — Standalone CHOICES block (for a dedicated Choice scene):

SCENE ending_choice_scene

CHOICES ending_choice_scene
  -> "Save the village" ending_village
  -> "Save the princess" ending_princess
  -> "Flee and survive" ending_coward

Conditional choices: Add a condition in square brackets after the target scene ID:

CHOICES
  -> "Unlock the gate"        gate_open     [hasKey = true]
  -> "Force the gate open"    gate_forced   [strength >= 8]
  -> "Look for another way"   gate_bypass
  -> "Give up"                retreat_scene

Choice style when condition fails — add a style keyword after the condition:

CHOICES
  -> "Buy the sword"   shop_sword  [gold >= 100]  locked    "Not enough gold."
  -> "Buy the staff"   shop_staff  [gold >= 80]   grayed    "Not enough gold."
  -> "Just browse"     shop_browse

Syntax for conditional choices with locked style and alternative text:

-> "Button text" target_scene [condition] style "alternative text when locked"

Choice actions: Choices can trigger variable or inventory operations on click. Add ! actions after the condition (or after the target if no condition):

CHOICES
  -> "Defend the village" village_aftermath ! heroism += 10 ! villageSaved = true
  -> "Run away"           coward_path       ! heroism -= 5 ! shame = true
  -> "Buy the potion"     shop_after        [gold >= 20]   ! gold -= 20 ! add:healing_potion

Action syntax:

23.8.5 Triggers within a Scene

Scene triggers are declared with trigger: lines. They execute at scene entry and follow Capsule's standard trigger logic (top-to-bottom, first redirect wins).

SCENE throne_room
  bg: throne.webp
  trigger: start [hasRoyalSeal != true] goto: throne_denied
  trigger: start [day >= 7] goto: late_arrival
  say king: "Ah, you finally come before me."

Syntax: trigger: when [condition] action: target

Multi-action triggers: Separate actions with |:

trigger: start [enemyMet = false] set: enemyMet = true | sound: sting.ogg | goto: ambush_intro

23.9 LOGIC Scene

Logic Scenes are invisible routing nodes. Declare them by adding logic: true to a SCENE block. They must have at least one trigger: or next: to avoid creating a dead-end.

SCENE hub_district
  logic: true
  trigger: start [district = "market"]  goto: market_scene
  trigger: start [district = "temple"]  goto: temple_scene
  trigger: start [district = "docks"]   goto: docks_scene
  next: district_default

SCENE calc_damage
  logic: true
  trigger: start set: damage = dice(1,8) | set: enemyHP -= damage
  next: combat_check

23.10 INVENTORY Block

Defines all collectible items in one block. Each line after INVENTORY declares one item.

INVENTORY
  healing_potion  "Healing Potion"  💊  "Restores 5 HP."     stack:10  consumable:true
  ancient_key     "Ancient Key"     🗝️  "Fits an old lock."  stack:1   consumable:false
  gold_coin       "Gold Coin"       🪙  "Shiny."             stack:99  consumable:false
  map_of_aetheria "Map of Aetheria" 🗺️  "Marks safe routes." stack:1   consumable:false

Syntax per item: id "Display Name" icon "Description" stack:N consumable:true/false

23.11 HUD Block

Configures the on-screen variable display.

HUD
  enabled: true
  position: top-left
  style: compact
  background: dark
  show: gold        icon:💰
  show: health      icon:❤️
  show: mana        icon:🔮
  show: reputation  icon:👑  style:detailed

23.12 CG_GALLERY Block

Declares unlockable gallery items (images and videos).

CG_GALLERY
  cg_lyra_smile     "First Smile"       image  lyra_smile.webp       category:"Characters"
  cg_kael_heroic    "The Captain Stands" image  kael_battle.webp     category:"Main Story"
  cg_ending_good    "A New Dawn"         video  ending_good.mp4      category:"Endings"
  cg_ending_bad     "Ashes of Aetheria"  video  ending_bad.mp4       category:"Endings"
  cg_secret_room    "The Developer's Room" image secret.webp         category:"Secret"

Syntax: id "Title" image/video file_url category:"Category Name"

23.13 Complete Scene Example — Putting It All Together

Here is a fully-featured scene demonstrating all syntax elements working together:

# ─────────────────────────────────────────────────────────
# Chronicles of Aetheria — Chapter 1 Opening
# ─────────────────────────────────────────────────────────

SCENE chapter1_start
  bg: forest_dawn.webp
  music: ambient_morning.ogg
  effect: floating_dust
  filter: warm
  camera: ken_burns 0.2 20
  transition: fade_black
  char: elara default left
  char: kael default right

  say: "Year 412 of the New Era. The war has been over for three years."
  say: "But not everyone has accepted the peace."

  expr elara: happy
  say elara: "Finally! I can see the capital from here, {actor:kael}."

  expr kael: smirk
  say kael: "Don't celebrate yet. We still have a [b]long[/b] road ahead."

  trigger: start [ch1_started = false] set: ch1_started = true

  CHOICES
    -> "Press forward quickly"     ch1_fast    ! resolve += 5
    -> "Rest before continuing"    ch1_rest
    -> "Check the map"             ch1_map     [has:map_of_aetheria]  locked "You have no map."

23.14 Full Project Template

A minimal but complete .cvl file for a new project:

# ═══════════════════════════════════════════
# my_game.cvl — CapsuleScript v1.9
# ═══════════════════════════════════════════

CONFIG
  title: "My Visual Novel"
  languages: en
  autostart: false
  devmode: false

VARIABLE name type default
  heroName     text     "Alex"
  gold         number   100
  affection    number   0
  hasKey       bool     false
  metNPC       bool     false

ACTOR hero
  name: "{actor:hero}"
  color: #4CAF50
  sprite default: hero_neutral.webp
  sprite happy:   hero_happy.webp
  sprite sad:     hero_sad.webp

ACTOR elara
  name: "Elara"
  color: #D4AF37
  sprite default: elara_neutral.webp
  sprite happy:   elara_smile.webp
  sprite sad:     elara_tears.webp
  sprite angry:   elara_angry.webp

INVENTORY
  healing_potion  "Healing Potion"  💊  "Restores health."  stack:5   consumable:true
  old_key         "Old Key"         🗝️  "Opens old locks."  stack:1   consumable:false

HUD
  enabled: true
  position: top-left
  style: compact
  background: dark
  show: gold    icon:💰
  show: affection icon:💕

# ─────────── SCENES ───────────

SCENE start
  bg: title_screen.webp
  music: main_theme.ogg
  transition: fade_black
  say: "A story begins..."
  next: intro

SCENE intro
  bg: village_morning.webp
  effect: floating_dust
  camera: slow_zoom 0.1 30
  char: elara default center
  say: "The village of Ashfeld. A place you have called home your whole life."
  say elara: "Oh! You're finally awake, {heroName}."
  CHOICES
    -> "Good morning, Elara." intro_friendly ! affection += 5
    -> "Leave me alone."      intro_rude     ! affection -= 3
    -> "What happened?"       intro_confused

SCENE intro_friendly
  char: elara happy center
  say elara: "Someone's in a good mood today! Here, I made breakfast."
  next: village_hub

SCENE intro_rude
  char: elara sad center
  say elara: "...I see. I'll leave it on the table then."
  next: village_hub

SCENE intro_confused
  char: elara default center
  say elara: "You don't remember? There was a [shake]loud noise[/shake] last night."
  next: village_hub

SCENE village_hub
  bg: village_square.webp
  music: village_theme.ogg
  say: "The village square is quiet. Where do you go?"
  CHOICES
    -> "Visit the market"      market_scene
    -> "Go to the old well"    well_scene    [metNPC = true]  hidden
    -> "Check your inventory"  check_inv
    -> "Leave the village"     road_to_city  [gold >= 50]     locked  "You need at least 50 gold to travel."

23.15 DSL Expressions — Conditions & Operators

All conditions used in triggers, choices, and scene logic follow the same syntax:

Combining conditions — use AND between multiple conditions:

trigger: start [rep_guild >= 10 AND day < 7] goto: guild_mission
-> "Join the council" council_scene [level >= 5 AND hasRing = true]

23.16 Advanced .cvl Patterns

Pattern 1: Branching Narrative Structure

SCENE chapter2_hub
  logic: true
  trigger: start [ch2_route = "guild"]   goto: guild_intro
  trigger: start [ch2_route = "cult"]    goto: cult_intro
  trigger: start [ch2_route = "neutral"] goto: neutral_intro
  next: neutral_intro  # fallback

# Each route is a separate scene chain...
SCENE guild_intro
  bg: guild_hall.webp
  music: guild_theme.ogg
  char: guild_master default center
  say guild_master: "Welcome to the Guild, recruit."
  next: guild_chapter2_main

Pattern 2: Global Events (Persistent Triggers)

Declare global events that fire on any scene where the condition becomes true:

GLOBAL_EVENT check_low_health
  condition: [health <= 0]
  action: goto: game_over

GLOBAL_EVENT reputation_milestone
  condition: [reputation >= 100]
  action: set: title = "Champion" | goto: title_unlock_scene

Pattern 3: Dice Roll System (D&D Style)

SCENE strength_check
  logic: true
  trigger: start set: roll_result = dice(1,20) + strengthMod
  trigger: start [roll_result >= 20] goto: door_critical
  trigger: start [roll_result >= 15] goto: door_success
  trigger: start [roll_result >= 10] goto: door_partial
  next: door_fail

SCENE door_critical
  bg: door_open.webp
  say: "Critical success! You rip the door clean off its hinges. [rainbow]Impressive.[/rainbow]"
  next: treasure_room

Pattern 4: Multi-Chapter Saga with Variable Transfer

SCENE chapter1_finale
  logic: true
  # These variables will carry over to chapter2.html
  trigger: start set: ch1_complete = true
  trigger: start [villageSaved = true] set: reputation += 25
  next: chapter1_end_screen

SCENE chapter1_end_screen
  bg: credits_ch1.webp
  music: ending_theme.ogg
  say: "[b]End of Chapter I[/b]"
  say: "Your choices echo forward..."
  # Jump to next chapter file is configured in CONFIG: nextfile: chapter2.html

23.17 Common Mistakes & How to Fix Them

23.18 CapsuleScript Quick Reference Card

═══════════════════════════════════════════════════════
CAPSULESCRIPT v1.9 — QUICK REFERENCE
═══════════════════════════════════════════════════════

BLOCKS
  CONFIG              Global project settings
  VARIABLE            Declare all variables
  ACTOR id            Define a character
  SCENE id            Define a scene
  CHOICES             Choice menu (inside or outside SCENE)
  INVENTORY           Define collectible items
  HUD                 Configure variable overlay
  CG_GALLERY          Declare unlockable gallery items
  GLOBAL_EVENT id     Declare persistent trigger

SCENE PROPERTIES
  bg:           Background image or video
  music:        Looping music
  sfx:          One-shot sound effect
  effect:       Particle effect (rain, snow, sakura...)
  filter:       Color filter (sepia, noir, warm...)
  overlay:      Additional image layer
  transition:   Entrance animation
  camera:       Camera mode [intensity] [duration]
  char:         actorID expression position
  next:         Auto-next scene ID
  logic: true   Mark as Logic Scene (invisible)
  trigger:      Conditional trigger (see below)

DIALOGUE
  say actorID: "text"       Character speaks
  say: "text"               Narration (no speaker)
  expr actorID: expression  Change expression mid-scene

  Multilingual: say actor: "EN" | "FR" | "ES"
  Tags: [b] [i] [u] [shake] [wave] [rainbow]
  Vars: {variableName}  {actor:actorID}

CHOICES
  -> "text" scene_id
  -> "text" scene_id [condition]
  -> "text" scene_id [condition] locked/hidden/grayed "alt text"
  -> "text" scene_id ! var = val ! var += n ! add:item

TRIGGERS
  trigger: start/end [condition] goto: scene_id
  trigger: start/end [condition] set: var op val
  trigger: start/end [condition] sound: file.ogg
  trigger: start/end [condition] action1 | action2 | ...
  trigger: start/end (no condition = always fires)

CONDITIONS
  [var = val]    [var != val]   [var > val]  [var < val]
  [var >= val]   [var <= val]
  [has:itemID]   [!has:itemID]
  [condA AND condB]

OPERATORS in set/actions
  = (assign)    += (add)    -= (subtract)
  add:itemID    remove:itemID

ACTOR PROPERTIES
  name: "Display Name"
  color: #hexcode
  sprite expressionName: url

VARIABLE DECLARATION
  varname  number/text/bool  defaultValue

═══════════════════════════════════════════════════════

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

24.3 Official Capsule Resources

24.4 VN Community & Asset Sources