Advanced Topics

Project DVN

Everything in this chapter is optional.

Most projects will never need anything here.

But if you want to change how DVN thinks, renders, executes, or exists - this is where you begin.

Contents


Quantum engine

Internal concept storage and timeline reconciliation. Only touch if you know why you woke up with this idea.

DVN includes a quantum execution model rather than a traditional linear runtime.

This system ensures that narrative behavior, randomness, and engine flow remain consistent and reproducible - even across saves, reloads, rewinds, and branching runtime paths.

The goal of the quantum layer is not to track player choices as data, but to track the state of the engine's universe.

What it does

DVN's quantum engine handles:

  • Deterministic randomness
  • Timeline collapses on load
  • State divergence on rewind or replay
  • Universe resets when starting a new game

This ensures that the runtime behaves like a consistent timeline rather than a loosely stitched sequence of isolated actions.

Key concepts

DVN models runtime using the following ideas:

Concept Meaning
Universe A complete runtime state from game start to the present moment
Branch A new execution timeline created by rewinding or replaying
Collapse A state merge event (loading, restarting, or resolving RNG outcomes)
Seed continuity Randomness behaves consistently based on the universe state

Example behavior (conceptually)

Imagine a moment in the game where something random happens (character reaction, background noise variation, etc.).

  • If the player reloads and reaches that moment again, the result will be the same - because the universe state did not branch.
  • If the player rewinds or jumps through history and then returns to that point, the system treats this as a new timeline, and the outcome may differ.
  • Starting a new game creates a new universe, meaning nothing carries over.

There is no direct API to manipulate the quantum system - it is internal and automatic.

When to use this

Most games don't need to interact with the quantum system directly.

It becomes relevant if your VN includes:

  • Timeline mechanics
  • Looping, déjà-vu, or meta-awareness design
  • Procedurally influenced narrative beats
  • Replay-dependent storytelling
  • Variable behaviors tied to universe continuity

When you can ignore it

If your VN is:

  • Linear
  • Branching in a traditional VN sense
  • Not dependent on deterministic randomness
  • Not manipulating time or replay behavior

- you never need to think about this system.

Threading / concurrency

Because sometimes one universe at a time isn't fast enough.

Generally you don't need threading, but in the absolute event you do then you can use the std.concurrency from D.

https://dlang.org/phobos/std_concurrency.html

However you should note that you shouldn't modify UI from another thread, but there is a certain function that can be used to send signals to the main thread so you can modify the UI with state obtained in a different thread.

The function can be found in the Application class, but it requires you to get the application instance using getApplication().

void sendMessage(Action action);

Action is simply defined as:

alias Action = void delegate();

Multi-Window / Multi-Instance Support

One game is fine. Multiple simultaneous timelines? Better.

Most games will never need additional windows, but the support is there if you ever need it.

To create a window simply call createWindow() on the Application class.

Window createWindow(string title, IntVector size, bool isFullScreen);

Note: you need to register your views with the created window, else you cannot display them.

Example:

auto myWindow = getApplication().createWindow("My Window", IntVector(800, 400), false);

Internal Engine Architecture Overview

For reading, not rewriting.

(unless you're very brave).

This section provides a high-level understanding of how DVN is structured internally.

You do not need this information to create a standard VN - it is intended for advanced users extending, modifying, or integrating DVN with custom systems.

Core Design Principles

DVN is built on a few internal architectural rules:

  • Data-driven - scripts, configuration and assets define behavior rather than hard-coded logic.
  • Modular - systems are isolated and replaceable.
  • Event-driven - most behavior is triggered by events rather than direct engine calls.
  • Runtime-oriented — the scene graph represents the live state of the game.

Major Engine Layers

Layer Description
Application Layer Handles platform initialization, windows, and runtime lifecycle.
View System Determines what the player sees (main menu, settings screen, gameplay view, etc.).
Scene System / Scene Graph The core runtime structure: characters, text, images, animations, audio, logic, etc.
Rendering Pipeline Translates scene graph and view state into actual drawn output.
Input & Interaction Layer Handles player input and routes it to the appropriate active view or scene node.
Scripting Layer Parses and executes external script files, populating and modifying the scene graph.
Resource System Loads, caches, and manages assets (images, sounds, fonts, scripts, metadata).
Quantum Layer Manages deterministic runtime state, seed continuity, and timeline behavior.
Serialization & Storage Handles saving, loading, and state persistence.

Execution Flow (Simplified)

Startup ->
  Load Settings ->
  Initialize Resources ->
  Initialize Views ->
  Load Main Script ->
  Populate Scene Graph ->
  Enter Frame Loop ->
      Process Input
      Update Scene State
      Render Frame
      Apply Quantum State Rules

What Can Be Modified

You can safely modify or extend:

  • Views
  • Scene node types
  • Scripting behavior
  • Rendering pipelines
  • Input handling
  • Serialization model
  • Resource loaders

What Should Not Be Modified

Unless you're rebuilding DVN or creating a fork, avoid altering:

  • The frame loop
  • Core scene graph mutation rules
  • The quantum engine
  • Internal UI routing
  • Low-level rendering glue code
  • Threading model

These systems maintain consistency across the entire runtime and are not intended to be restructured during normal project development.

Summary

This overview exists to help advanced developers understand the internal shape of DVN.

Most users never need to interact with these layers directly, but if you're extending or modifying the engine, knowing where systems live and how they interact prevents confusion and unintended behavior.