#player #visual #engine #color #net #font #novels

app vngine

A player and engine for visual novels

1 unstable release

0.1.0 Sep 30, 2021

#36 in #visual

MIT/Apache

2MB
1K SLoC

Formats

There are multiple files needed:

  • the project file (.vng)
  • the petri net and the mapped names (.pns, .pnk)
  • the story (.story)

You might also have a look at the simple example project.

The project file

This file has a line based format representing a key-value list. The list is separated by a space. It has multiple lines like this:

key1 value1
key2 value2
key3 value3

Currently keys for these features are supported:

  • file paths
  • colors
  • fonts
  • timing

File paths

These keys specify the file paths. They are followed the a file path.

These three files are supported:

  • net
  • names
  • story

They default to the name of the project file (project.vng), but with an appropriate extension (project.pns, project.pnk, project.story).

Colors

The color keys are used to specify the color of a specific UI element.

These color keys are currently supported:

  • background
  • dialog-fill
  • dialog-line
  • choice-default-fill
  • choice-default-line
  • choice-select-fill
  • choice-select-line
  • revert-default-fill
  • revert-default-line
  • revert-select-fill
  • revert-select-line

By default, all outlines (line) are white and all fillings (fill) and the background (background) are black.

A color can either be a color name or a hexadecimal representation.

These color names are available:

  • black
  • white
  • red
  • green
  • blue
  • yellow
  • cyan
  • magenta

The hexadecimal representation can have different numbers of digits:

  • 1 or 2 digits => gray value
  • 3 or 6 digits => RGB value
  • 4 or 8 digits => RGBA value

Fonts

There are also keys to specify alternative fonts.

You can specify up to eight different fonts, which all may or may not have these three features:

  • bold
  • italic
  • monospace

The specific keys are these:

  • default-font
  • default-font-bold
  • default-font-italic
  • default-font-bold-italic
  • mono-font
  • mono-font-bold
  • mono-font-italic
  • mono-font-bold-italic

Timing

These specify different timings (in seconds)

  • letter-time: The time until the next letter appears (default: 0.05s)
  • line-time: The time until the next line appears (default: 0.5s)
  • select-time The duration of the animaton when selecting a choice (default: 0.5s)

The petri net and the mapped names

The petri net file specifies the logic of the story. Especially which events need to be finished in order to enable new ones.

The name mapping is important to know, which index of the petri net is mapped to which name.

This way, it's possiple to change the order of the story segments nets to your liking.

The story

The story file is a line based file format inspired by markdown.

Headers start with a #.

Every line will represent a line in the text box. Every text box is represented by a text block (multiple text lines without a newline).

You can add a name followed by a colon (Name:) before a text block to indicate someone saying the text. The name might be in the same line or in its own line.

You can add formatting by writing a special symbol. Everything after this symbol will be formatted that way. A second one of the same special symbol will remove the formatting again. At the end of a line, all formatting is reverted to normal.

These formattings are supported:

  • * bold
  • / italic
  • ' monospace
  • ^ superscript
  • | subscript
  • _ underscore
  • ~ strikethrough

All formattings can be combined. Combining superscript and subscript (^|) will result in small text.

You can ignore formattings and display the characters instead by adding a \ before them.

The first line of the first text block of a segment will be the name of the choice.

Usage

Opening the project

Just open the project file.

On command line, that's done this way:

vngine [project.vng]

Controls

You can control using the mouse or the arrow keys.

There are three actions:

  • confirm
  • revert
  • select

You press the left mouse button or the right arrow key to confirm and advance the story.

You press the right mouse button or the left arrow key to revert to the previous state.

When there are multiple choices, you can select the choice by moving the cursor or using the arrow keys up and down.

If the choice is a normal choice, you use the confirm action to confirm your choice. The revert action reverts to the previous state.

But since choices can be reverted in different orders, there are also reversion choices. In that case, you use the revert action to confirm your choice, since it reverts the story. The confirm action still advances the story.

Dependencies

~8–12MB
~235K SLoC