Visual Novels

Visual Novel mode changes how a scene is presented. The story still uses normal Storyfall scenes, choices, variables, effects, saves, narration, audio, and publishing. The difference is that the scene shows a background and character sprites behind a dialogue box, and each paragraph becomes one dialogue box the reader taps through before the choices appear.

You do not write a separate script. The scene’s normal text and choices are used as-is. To change the background or who is on stage partway through, select the paragraph and use Scene visuals.

Turn On Visual Novel Mode

Open the Visual Novel panel from the editor sidebar, then select the scene you want. Turn on Visual novel mode for that scene.

When it is on, the panel shows controls for:

The asset menus use the story’s Visual Novel asset library. Background assets appear in the Background menu. Sprite assets appear in the slot menus.

For each slot that has a sprite, you can also set an Entrance animation (how the character appears: fade, slide in from the left or right, rise, or zoom), Entrance duration in milliseconds, an Idle animation (a subtle breathe or sway loop), Idle speed in milliseconds, and, under Position & scale, nudge the sprite’s X and Y, change its scale, or mirror it.

Turn on Dim non-speaking characters to spotlight whoever is talking: linked characters who are not the current speaker fade back. This needs each sprite linked to the NPC it shows (see Manage Visual Assets) and a speaker set on the paragraph.

Manage Visual Assets

The Visual Novel panel has three tabs: This Scene (the stage controls above), This Story (this story’s asset library), and Library (assets from your other stories).

On the This Story tab, drag one or several images onto the upload box, or click to choose them. Each file is staged with a name and, for sprites, a variant; edit those, then click Upload. Choose Background for locations and full-stage images, or Sprite for characters and props that fill the left, center, or right slots. Give sprites a variant label like neutral, worried, or injured when you want several versions of the same character.

Use Create sprite from a character image to copy an existing NPC or character image into the asset library. The copied sprite is independent, so changing or deleting it does not change the original NPC or character portrait.

Rename an asset, switch it between Background and Sprite, or delete it from the asset list. If an asset is still used by a scene’s stage, Storyfall asks you to clear those references before deleting it.

When you edit a sprite, you can also link it to the Character (NPC) it depicts. That link powers Dim non-speaking characters, and it works both ways: open an NPC from the NPCs panel and its edit window lists the visual novel sprites linked to that character.

Reuse Assets From Other Stories

The Library tab shows the backgrounds and sprites from your other stories, grouped by story. Search by name or story, then click Add to story to copy an asset into the current story, or Add all to copy a whole story’s set at once. Assets you have already brought in show as Added.

Imported assets are copies, so editing or deleting them in this story never changes the original. Only your own stories appear here.

Write Dialogue

Just write the scene’s text normally. Each paragraph becomes one dialogue box the reader clicks, taps, or advances with Space or Enter, in order, before the choices appear. If typewriter text is still revealing, that input finishes the current beat first. The next input advances to the next beat.

To show an NPC’s name above a line, select the paragraph, open Scene visuals, and choose an NPC from Speaker. If you have not created any NPCs yet, click Add NPCs from that control to open the NPCs panel.

A paragraph with No speaker selected has no name-plate. Bold text stays as normal formatting inside the dialogue.

Change The Visuals Mid-Scene

The whole scene starts with the background and sprites you set in the panel, but you can change them as the reader taps through. Select a paragraph in the scene editor, and a Scene visuals button appears in the selection menu (the same way you assign a narration voice to selected text). Use it to set that paragraph’s background, sprites, and speaker.

When the reader reaches that paragraph, the stage updates. Paragraphs you leave alone keep whatever the previous paragraph showed, so you only tag the moments where something changes. This stays inside one scene, so your choices and story tree are untouched.

Change The Music Mid-Scene

You can change the background music the same way. Type @ in a paragraph and pick a music track to embed a music cue. When that beat shows, the track becomes the scene’s looping background music. See Audio for the full behavior.

Use The Code Editor

The Code Editor sets the scene’s stage at the top of the scene with a vn stage: block:

vn stage:
  background "Apartment Night"
  dim inactive
  left sprite "Mara neutral" x -8 scale 1.05 enter slide-left enter-ms 700 idle breathe idle-ms 4200
  right sprite "Ilya worried"

The scene’s dialogue is just its normal text below that. Sprite lines take optional x, y, scale, mirror, opacity, and z placement plus enter and idle animations. Use enter-ms for entrance duration and idle-ms for idle speed, both in milliseconds. dim inactive turns on speaker dimming for the scene. NPC speaker assignments are set from the visual editor’s Scene visuals menu.

Per-paragraph stage changes you make with Scene visuals are written as @vn directive lines just before the paragraph (for example @vn background "Throne Room" and @vn left sprite "Mara (worried)"), so they survive editing the scene in the Code Editor. A per-paragraph sprite line takes the same placement, animation, and timing tokens, so a single beat can move or animate a character. See Code Editor for the full list.

Timers And Choices

Scene timers start after the final paragraph. Effects and choices still work normally. In hosted play, HTML export, and offline play, choices appear over the scene background and use the same translucent background as the dialogue box. They keep the usual choice behavior, keyboard shortcuts, input fields, dropdowns, and multiplayer voting UI where available. Ending and dead-end sections stay below the scene.

Visual Novel staging is presentation only, so it does not change variables, relationship scores, visits, or history by itself.

Export And Offline Play

Visual Novel scenes work in hosted play, HTML export, and offline play. Storyfall-hosted backgrounds and sprites are bundled into HTML exports and mobile offline downloads. Hand-pasted external image URLs stay remote.