📖 NovellaEngine

A Modular Visual Novel Framework for Unity | C# | Branching Narrative & Save Systems

A lightweight, extensible framework for building visual novels and interactive storytelling experiences in Unity. Features modular dialogue parsing, save/load serialization, choice-driven branching, and designer-friendly tooling—built for rapid iteration and cross-platform deployment.

---

✨ Core Features

• 🧩 Modular Dialogue System: YAML/JSON-based script parsing with conditional logic, variables, and tags
• 💾 Robust Save/Load: Serializable game state with chapter checkpoints, player choices, and inventory tracking
• 🔀 Branching Narrative Engine: Graph-friendly structure for non-linear stories; visualizable via custom editor tools
• 🎨 Designer-Friendly Workflow: Custom Unity Editor windows for script editing, character management, and scene linking
• 🌐 Localization-Ready: Externalized text tables with runtime language switching (7+ language pattern support)
• 🧪 Testable Architecture: Decoupled logic layers enable unit testing for narrative flow and state management

---

🏗️ Technical Architecture

Assets/
├── NovellaEngine/
│   ├── Core/
│   │   ├── NovelManager.cs        # Main controller: scene flow, state persistence
│   │   ├── DialogueParser.cs      # YAML/JSON parser with conditional evaluation
│   │   ├── SaveSystem.cs          # JSON serialization + checkpoint management
│   │   └── VariableStore.cs       # Runtime variable tracking for branching logic
│   ├── Editor/
│   │   ├── ScriptEditorWindow.cs  # In-editor dialogue script editor
│   │   ├── CharacterManager.cs    # Sprite/voice assignment UI
│   │   └── BranchVisualizer.cs    # Optional node-graph preview (WIP)
│   ├── UI/
│   │   ├── DialogueBox.cs         # Responsive text display + typewriter effect
│   │   ├── ChoicePanel.cs         # Dynamic button generation for player choices
│   │   └── SaveLoadMenu.cs        # Checkpoint selection UI
│   └── Data/
│       ├── Scripts/               # Example .novel YAML/JSON files
│       ├── Characters/            # ScriptableObject character definitions
│       └── Configs/               # Localization tables, theme settings
└── Tests/
    ├── DialogueParserTests.cs
    └── SaveSystemTests.cs

Key Design Patterns

• Data-Driven Scripting: Story logic lives in external files—no code recompilation for content updates
• Event-Driven Flow: DialogueAdvancedEvent, ChoiceSelectedEvent decouple UI, logic, and audio
• State Isolation: Save data is serializable POCO classes, independent of Unity MonoBehaviour lifecycle
• Extensibility Hooks: Virtual methods and interfaces allow custom effects, transitions, and integrations

---

🚀 Getting Started

Requirements

• Unity 2022.3 LTS or newer
• .NET Standard 2.1 compatibility
• Basic familiarity with Unity ScriptableObjects and JSON serialization

Setup

1. Clone this repo into your Unity Projects/ directory
2. Open the project in Unity Hub → Editor
3. Import the NovellaEngine package via Package Manager or drag the folder into Assets/
4. Open Scenes/DemoScene.unity and press Play to see the framework in action

Quick Start: Writing Your First Scene

# example.novel
scene: intro
background: bg_bedroom
characters:
  - id: protagonist
    name: "You"
    sprite: sprite_hero
  - id: friend
    name: "Alex"
    sprite: sprite_alex

dialogue:
  - character: friend
    text: "Hey! Ready for the adventure?"
    choices:
      - text: "Absolutely!"
        next: scene_adventure_start
        set: { enthusiasm: +1 }
      - text: "Maybe later..."
        next: scene_postpone
        set: { enthusiasm: -1 }

// Load and play in your MonoBehaviour:
var novelManager = FindObjectOfType<NovelManager>();
novelManager.LoadScript("example.novel");
novelManager.StartDialogue();

---

💡 Example: Adding a Custom Effect

// Create a new dialogue effect (e.g., screen shake on dramatic lines):
public class ScreenShakeEffect : IDialogueEffect
{
    public void OnLineStart(DialogueLine line, NovelContext context)
    {
        if (line.HasTag("dramatic"))
        {
            Camera.main.GetComponent<CameraShake>().Shake(0.3f, 0.5f);
        }
    }
}

// Register in NovelManager:
novelManager.RegisterEffect("shake", new ScreenShakeEffect());

---

🙏 Acknowledgements

• Inspired by visual novel engines like Naninovel, Fungus, and Ren'Py—built with a focus on modularity and C# purity
• Built for educational and portfolio purposes; not intended for commercial deployment without further testing
• All original code authored by Nicholas Wilson Kurniawan; design patterns learned from public Unity documentation and community resources

Note: This framework is a learning project. For production use, always validate serialization security, memory management, and platform-specific behavior.

---

🤝 Contributing

This is a reference implementation and learning tool. Feel free to:

• 🍴 Fork and extend with your own effects, parsers, or UI themes
• 🐛 Report bugs or suggest architecture improvements via Issues
• 💬 Discuss narrative design patterns or engine extensions in Discussions

For educational use: please credit the original author and link back to this repo.

---

📬 Connect & Explore More

📧 nwkemail@gmail.com | 🎓 B.Eng. Computer Science, HKU | 🎮 Gameplay Engineer (UE5/Unity)

---

💡 Tip for recruiters: This project demonstrates data-driven design, serialization patterns, and editor tooling—skills directly transferable to narrative systems, quest editors, or content pipeline tools in AAA studios.

Built with clean C#, player-first narrative design, and a passion for interactive storytelling. 📖✨