TextNovelEngine

TextNovelEngine is a Java desktop engine for building and playing text-based visual novels.

The project has moved past the early prototype phase and is now close to its first complete usable version. The current engine already supports external story loading, hierarchical story flow, branching choices, action-based jumps, a custom Swing reader window, and a stable gameplay/menu loop. The main missing gameplay feature is persistent save/load.

Current Status

• Project renamed from Visual Novel Engine to TextNovelEngine
• Core architecture is already in place and playable
• Stories are now loaded from external .java files outside the source tree
• The engine is designed as a reusable runtime, not as a single bundled demo story
• Save and load buttons exist in the UI, but their implementation is still pending

What Works Right Now

• Hierarchical story model: Story -> Day -> Section -> Scene -> Block
• Supported block types: Narrative, Dialogue, Monologue, Choice, Action
• Branching choices through Option
• Scene jumps by sceneId
• Structured jumps to day, section, scene or block through Jump and JumpTarget
• External story discovery, runtime compilation and loading
• Main menu with story selection
• Settings and creator screens managed by the engine state machine
• Toolbar-based desktop UI built with Swing
• Typewriter-style text rendering and controlled input flow

Project Structure

src/main/java/engine/core Core runtime, state flow and progress-related classes.

src/main/java/engine/story/model Story hierarchy: Story, Day, Section, Scene.

src/main/java/engine/story/blocks Playable content blocks and branching primitives.

src/main/java/engine/story/controller Navigation and active story position management.

src/main/java/engine/story/external Discovery, compilation and loading of external stories.

src/main/java/engine/story/jump Helpers for structured navigation across the story hierarchy.

src/main/java/engine/ui Custom console-style Swing window and rendering support.

Where Stories Live

The engine scans the user's documents directory and looks for external story source files in:

• ~/Documents/TextNovelEngine/stories
• or ~/Dokumenty/TextNovelEngine/stories on systems that use the localized Polish folder

Each playable story should be a .java file that exposes:

• createStory()
• optionally getStartScene() or getStartSceneId()

At startup, the engine:

1. finds .java story files in the stories directory,
2. compiles them,
3. loads the selected story class dynamically,
4. creates a Story instance,
5. starts from the declared start scene or from the default beginning.

Minimal Story Example

import engine.story.blocks.Dialogue;
import engine.story.blocks.Narrative;
import engine.story.model.Day;
import engine.story.model.Scene;
import engine.story.model.Section;
import engine.story.model.Story;

public class HelloStory {

    public static Story createStory() {
        Story story = new Story();

        Day day = new Day(0);
        Section section = new Section(0);
        Scene intro = new Scene(
                "intro",
                new Narrative("A cold wind moves through the empty street."),
                new Dialogue("Narrator", "Welcome to TextNovelEngine.")
        );

        section.addScene(intro);
        day.addSection(section);
        story.addDay(day);

        return story;
    }

    public static String getStartScene() {
        return "intro";
    }
}

Design Direction

TextNovelEngine is being built as a clean and expandable base for interactive storytelling in Java. The current direction focuses on:

• keeping story authoring code straightforward,
• separating engine runtime from story content,
• supporting branching narrative flow without overcomplicating the API,
• preparing the codebase for save/load and richer game state in the next iteration.

Author

Maciej Serafin

Computer Science student at PJATK Gdansk.

License

This project is open-source and currently shared for educational, creative and experimental purposes.