vinora-engine/docs/vnrs_specification.md

VINORA SCREENPLAY SPECIFICATION

Version 0.0.1 (14.10.2025)
Evgeniy "Parthen" Parfenyuk

1. Introduction

1.1 What is Vinora Screenplay?

Vinora Screenplay is plain text format for writing visual novel screenplays.

It's based on (and one-way compatible with) Markdown, simple markup language developed by John Grubber and Aaron Swartz in 2004. It was developed to simplify web pages writing.
While Markdown originally doesn't have specification (only Markdown.pl as a reference implementation), we use CommonMark for this role.

1.2 Why it's needed?

Vinora Screenplay is designed for use in the Vinora Engine. The goals of this visual novels engine is to be as simple and compatible as possible.

Markdown is a popular format. There is a good change that you're already familiar with *italic* or __bold__ syntax. So, by making Vinora Screenplay as Markdown-like language we fulfill both of our goals (it's simple to use since it's known and it's compatible with dozens of existing Markdown interpreters).

1.3 Comparison with another languages (TODO)

[...]

2. Definitions

2.1 Technical definitions

Character
is the smallest unit of text that carries a semantic or visual meaning in a writing system. It can be a letter, digit, punctuation mark, space, special character (e.g., "@" or newline), or another element used to represent information in text form.
NOTE: emojis are images, and not text characters.
So-called Unicode "combined characters" are considered (and rendered) as multiple separate characters.

Newline characters
are special characters that end a line. Depending of the system, default newline character would be CR (carriage return, \r), LF (line feed, \n) or even both (CR + LF).
NOTE: All of them are considered valid end of line, but they are replaced with LF (\n) character.

Whitespace characters
are characters which are rendered into whitespace. They are invisible, but they are affect formatting. For example, space character separate different words.
All newline characters are whitespace characters.
Full list of whitespace characters: tab (horizontal and vertical), space, carriage return, line feed, form feed.

Line
is a sequence of zero or more characters, that ends with newline or End Of File (EOF) condition. Line which has zero characters or only whitespace characters called empty line.

ASCII character
is a character supported by US-ASCII encoding. Since any existing encoding is an extension of ASCII, characters from ASCII is supported by nearly every computer.

2.2 Visual novels definitions

(Only techinal definitions goes here)

Visual novel (from )
A visual novel can be seen as a combination of a novel and a computer game: they're computer games with a large text based storyline and only little interaction of the player.
A typical visual novel consists of text over an anime-style background image and is accompanied by background music.
Throughout the game, the player usually has to answer a few questions which will have an effect on the story, thus playing a visual novel a second time while giving other answers may result in an entirely different plot.

ADV / NVL mode

• Adventure (ADV) is a VN mode, where text takes only a small part of the screen (and therefore, images take more space).
  
• Novel (NVL) is a VN mode, where text takes up a large part of the screen (sometimes even all of it, while images are in the background).
  Commonly, VN plays in ADV mode and switch to NVL for monologues.

Kinetic VN
is a VN without choices or gameplay. Term was popularised to name games from 'KineticNovel' publisher. Games with gameplay, but without choices called liniear plot.

Character points
Points awarded or deducted based on positive or negative interactions with a character. Typically hidden from the player, these points influence the storyline.

Hybrid VN
mix of traditional games (e.g. RPGs) and visual novel.