Skip to main content

Basic Concepts

This page introduces the core concepts you need to understand before building with Nongine. Everything in the editor revolves around these building blocks.

Nodes​

Nodes are the primary building blocks of your visual novel. Each node represents a discrete unit of functionality: displaying a scene, running dialog, presenting choices, evaluating conditions, playing audio, or executing logic. Nodes appear as cards on the graph canvas, each with a colored header indicating its type, a title, and connection handles (ports) on the left and right sides.

There are 17 node types organized into five categories: Flow, Content, Branching, Interaction, and Logic. You add nodes by double-clicking the canvas, dragging from the sidebar palette, or pulling a connection from an existing node's handle into empty space.

Edges​

Edges are the connections between nodes. They are drawn as lines from an output handle on one node to an input handle on another. Edges define execution order: when a node finishes its work, the runtime follows the outgoing edge to the next node.

Some nodes have multiple output handles. A Choice node has one output per option. A Condition node has "true" and "false" outputs. You create an edge by clicking an output handle and dragging to an input handle. You remove an edge by selecting it and pressing Delete.

Editor Modes​

Nongine has five editor modes, accessible from the mode switcher in the toolbar:

  • Graph — The visual flow editor. Pan, zoom, create nodes, draw edges, and design the high-level structure of your story.
  • Write — A focused text editor for authoring content inside Sequence nodes. Use slash commands to insert dialog, narration, sound effects, and more.
  • Split — A combined view showing the graph on the left and the Write editor on the right, so you can see structure and content simultaneously.
  • Design — A visual layout editor for customizing the player UI: textbox position and style, portrait placement, choice button appearance, and freeform decorations.
  • Assets — The asset library where you upload, organize, and manage backgrounds, characters, audio files, and sprites.

Switch modes with the toolbar buttons or the keyboard shortcuts Ctrl+1 through Ctrl+4.

Assets​

Assets are the media files that bring your visual novel to life. Nongine organizes them into four categories:

  • Backgrounds — Full-screen images used in Scene nodes.
  • Characters — Character definitions with named portraits (expressions). Each character has a name, a color, and a set of portrait images representing different emotions.
  • Audio — Sound effects (SFX) and background music (BGM) tracks.
  • Sprites — Additional images used for UI decorations, items, and overlays.

Assets are uploaded through the Asset Manager and stored in the cloud via Supabase. Once uploaded, they can be referenced from any node in your project.

Variables​

Variables store data that persists throughout a playthrough. Nongine supports four variable types:

  • Boolean — True or false. Use for flags like hasKey or metAlice.
  • Number — Numeric values. Use for scores, counters, affinity points, health.
  • String — Text values. Use for names, selected responses, locations.
  • Item — A special type for inventory items. Supports add/remove operations with quantities.

Variables are created in the Inspector's variables section or inline from any variable picker. They drive conditions, control branching, and can be interpolated into text using curly brace syntax: {playerName}, {score * 2}, {hp > 50 ? "healthy" : "hurt"}.

Theme​

The theme system controls the visual presentation of the player. It covers:

  • Textbox — Position, size, background color/image, opacity, blur, border, shape (rectangle or speech bubble), animation.
  • Typography — Font family, sizes, colors for character names, dialog text, narration, and system text. Text shadow, stroke, and letter spacing.
  • Portraits — Size, border radius, and position (left, right, or hidden).
  • Choices — Button background, hover state, border, layout (center, bottom, fullscreen), gap, and shadow.
  • Display Mode — ADV (replace text each line) or NVL (accumulate text in a scrolling log).
  • Typing Effect — Enable or disable typewriter-style text reveal with configurable speed.
  • Custom CSS — Write arbitrary CSS for full control over presentation.

Theme presets are available for quick setup, and per-character or per-scene overrides let you change the look contextually.

Layout​

The layout system provides freeform positioning of UI elements in the player. Instead of being locked to predefined positions, you can drag the textbox, portrait, name badge, choices, and click indicator to any position on screen. Each element is defined by a rectangle with x/y coordinates, width/height (as percentages of the viewport), and an anchor point.

Character slots (far_left, left, center, right, far_right) can also have their positions and scales customized. Decorations -- images placed on screen as overlays -- support opacity, z-index, blend modes, nine-slice rendering, and attachment to parent elements. Per-screen layouts let you have different arrangements for dialog, choice, NVL, chapter, and ending screens. A separate mobile layout can be defined for smaller viewports.

Runtime​

The runtime is the player engine that executes your graph. Starting from the Start node, it traverses edges, processes each node, fires runtime events (set background, show dialog, present choices, play audio), and manages the game state including variables, save/load, backlog, and audio channels. The runtime supports:

  • Save and load with screenshot thumbnails
  • Backlog (history of dialog and narration)
  • Variable interpolation and expression evaluation
  • Character enter/exit animations
  • NVL and ADV display modes
  • HTML export for standalone distribution

How They Work Together​

A typical visual novel starts at a Start node. Scene nodes set backgrounds and position characters. Sequence nodes deliver dialog, narration, sound effects, and visual effects step by step. Choice nodes let the reader make decisions, each option leading to a different branch. Condition nodes check variables to route the story based on prior choices. SetVariable nodes update state. Assets provide the images and audio that the theme and layout present in the runtime player. Understanding these concepts gives you the foundation to build anything from a short interactive scene to a full-length branching narrative.