Unity Visual Novel Framework

Notice

All graphics included in the example script were generated by AI, as were the character voices. If the original voice actor wishes to have their generated audio clips removed, please contact me, and I will ensure that it will be done. The music featured in the example was created by Peritune.

Note: This project is still under active development, so even if it's stable, some features may not be complete.

What is this project?

This is a visual novel framework for the Unity Engine. It allows you to write dialogue, character actions, scenery changes, visual effects, and many other elements into a story.

How does it work?

It uses a custom scripting language called "VNF" that is easy to learn and designed with character actions in mind, much like writing a screenplay.

Where can I find the documentation?

Complete documentation is not yet available. However, you can find a list of the most useful commands in the "Assets/External" folder, under a file called "VNF Documentation.odt".

Additionally, you can use the example scripts provided as a reference since the language itself follows easily replicable patterns.

You can find the example arc file inside "Assets/Data/Arcs/example_arc". And another simpler example file inside "Assets/Data/Arcs/effect_demo"

Scripting

In the "External" folder, you'll find a file named "VNP.xml." This file defines the scripting language, enabling proper syntax highlighting in Notepad++. While it's not required, it significantly enhances the writing experience.

Assets

This project uses various ScriptableObjects to store data related to the story, such as Arcs and Characters. All of these can be created by right-clicking in the Unity Editor and hovering over: Create/VN

Note: An Arc refers to a collection of scripts or a chapter.

To ensure the desired assets are available, you MUST reference them in the appropriate field within the Arc ScriptableObject.

Asset Folders:

• Character ScriptableObjects and Poses:
  Data/Characters

• Backgrounds:
  Data/Backgrounds

• Audio Files:
  Data/Audio

• Scripts, Voice lines and related ScriptableObjects:
  Data/Arcs

The entry point to the story will be the first Arc file in the Arcs array from the Director GameObject present in the scene.

Important!

Note: Currently, there is an issue where even Arcs without dialogue must have an empty Scene Voices entry that matches the Arc index, in order for the VNP scripts to compile correctly.

Notes

Note: Creating ScriptableObjects for backgrounds is not strictly required at this time.

Project Setup Instructions

Prerequisites

To run this project, you will need to install Unity 2021.3.39f. Follow the steps below to install the correct version and set up the project:

1. Install Unity Hub

1. Download and install Unity Hub from here.
2. Open Unity Hub after installation.

2. Install Unity 2021.3.39f

1. In Unity Hub, go to the Installs tab.
2. Click on the Install Editor button.
3. Select 2021.3.39f from the list of available versions. If it’s not listed:
   • Click Archive, which will redirect you to the Unity download archive.
   • Scroll down and find 2021.3.39f.
   • Click Download Archive, and use Unity Hub to install it.

3. Clone the Repository

1. Clone the project repository to your local machine: git clone git@github.com:romm27/unity-visual-novel-framework.git
2. Open Unity Hub and go to the Projects tab.
3. Click Add, then navigate to the folder where the project was cloned, and select it.

4. Open the Project

1. Select the project in Unity Hub.
2. Ensure Unity 2021.3.39f is selected as the version.
3. Click Open to launch the project in Unity.
4. Once it is up and running, remember to set the game preview aspect ratio to 16:9.

---

You're all set!