Configuration, JSON & CSV

Project DVN

The following document describes configurations, json parsing and csv parsing in DVN.

Contents


JSON parser

DVN includes a fully functional json parser.

JSON files are ideal for configuration, modding, localization, and storing structured data outside scripts.

It supports

  • All json types (including null)
  • Optional fields
  • Strict fields
  • Full unicode support
  • Unicode encodings (utf8, utf16, utf32)
  • Custom serialization/deserialization functions
  • Automatic type serialization/deserialization ex. classes, structs, associative arrays, arrays, integers etc.
  • Flow attributes (@JsonIgnore etc.)

Data example

public final class Translation
{
    public:
    final:
    string from;
    string to;
    bool isOption;
}

Serialization example


Translation[] translations;

...

string serializedJson;
if (!serializeJsonSafe(translations, serializedJson, true))
{
    return;
}

Output:

[{
    "from": "...",
    "to": "...",
    "isOption": false
}, ...]

Deserialization example

import std.file : readText;
auto text = readText("translations.json");

string[] errorMessages;
Translation[] translations;
if (!deserializeJsonSafe!(Translation[])(text, translations, errorMessages))
{
    throw new Exception(errorMessages[0]);
}

Settings system

Settings for DVN are located in the data/settings.json file.

GameSettings controls global behavior, UI appearance, default text formatting, audio settings, and other engine-level configuration used across the entire project.

This is the full spec:

/// 
public final class GameSettings
{
  public:
  final:
  this()
  {
    rubyOffset = 0.0;
  }

/// 
  string[string] fonts;
/// 
  string[] backupFonts;
/// 
  string[string] languages;
/// 
  string language;
/// 
  string defaultFont;
/// 
  string defaultTextColor;

/// 
  bool muteMusic;
/// 
  bool muteSoundEffects;
/// 
  int volume;

/// 
  string mainScript;
/// 
  int textSpeed;
/// 
  string title;
/// 
  string loadTitle;
/// 
  SaveFile[string] saves;

/// 
  bool fullScreen;

/// 
  string[string] defaultCharacterNameColors;
/// 
  string dialoguePanelBackgroundColor;
/// 
  string dialoguePanelBorderColor;
/// 
  string namePanelBackgroundColor;
/// 
  string namePanelBorderColor;

/// 
  string loadText;
/// 
  string backText;

/// 
  string[string] meta;

/// 
  string saveButtonText;
/// 
  string exitButtonText;
/// 
  string settingsButtonText;
/// 
  string autoButtonTextOn;
/// 
  string autoButtonTextOff;
/// 
  string quickSaveButtonText;
  
/// 
  string customStartView;

/// 
  string videoLoadingScreen;
/// 
  string videoLoadingMusic;

/// 
  bool disableLoadScreenMusic;
/// 
  SettingsImage dialoguePanelImage;
/// 
  SettingsImage namePanelImage;

/// 
  string loadingMusic;
/// 
  string mainMusic;

/// 
  string mainBackgroundVideo;

/// 
  string buttonTextColor;
/// 
  string buttonBackgroundColor;
/// 
  string buttonBackgroundBottomColor;
/// 
  string buttonBorderColor;
/// 
  string dropdownTextColor;
/// 
  string dropDownBackgroundColor;
/// 
  string dropDownBorderColor;
/// 
  string checkBoxBackgroundColor;
/// 
  string checkBoxBorderColor;
/// 
  string textBoxColor;
/// 
  string textBoxTextColor;
/// 
  string textBoxBorderColor;
/// 

/// 
  bool displayOptionsAsButtons;
/// 
  bool enableAutoSave;
/// 
  bool fadeInText;

/// 
  int textMargin;
/// 
  int textWrapSize;
/// 
  bool fadeInCharacters;
/// 
  bool hideSavedLabel;
/// 
  bool useLegacySceneButtons;

/// 
  int saveFileTextMatchPercentage;

/// 
  bool useLegacyCharacters;
/// 
  string useLegacyCharacterSplit;

/// 
  bool disableSwipeGesture;
/// 
  bool disableContinueArrow;
/// 
  int autoSpeed;

/// 
  bool clickTextBoxtoAdvance;
/// 
  int textPanelOpacityLevel;
/// 
  bool hideAutoIndicator;
/// 
  bool highlightNewText;
/// 
  string highlightNewTextColor;

/// 
  int windowFadeTime;
/// 
  int voiceTimingMultiplier;

/// 
  int dialogueTextLineSpacing;
/// 
  bool immersionMode;
/// 
  bool disableEffects;
/// 
  int historyMaxEntries;
///
  bool allowSameCharacterMultiple;
///
  bool displayRuby;
///
  double rubyOffset;
///
  string rubyStartChar;
///
  string rubyEndChar;
///
  bool shadowRuby;
}

/// 
public final class SettingsImage
{
  public:
  final:
/// 
  string path;
/// 
  SettingsSize size;
}

/// 
public final class SettingsSize
{
  public:
  final:
/// 
  int width;
/// 
  int height;
}

/// 
public final class SaveFile
{
  public:
  final:
  this() {}

/// 
  string id;
/// 
  string date;
/// 
  string originalScene;
/// 
  string scene;
/// 
  string text;
/// 
  string background;
/// 
  string music;
/// 
  string[string] meta;
/// 
  uint seed;
/// 
  int calls;
}

Most fields are optional unless stated otherwise - DVN will fall back to defaults when fields are missing.

Important: Do not modify GameSettings from code unless you fully understand the impact. It is intended to be configured through settings.json, not altered dynamically.

Runtime Settings

To modify settings at runtime, first fetch the global settings:

auto settings = getGlobalSettings();
settings.volume = 50;
EXT_SetSoundVolume(settings.volume);

To save updated settings:

saveGameSettings("data/settings.json");

Note: saveGameSettings must be called from the UI thread (the main DVN thread).

Example Flow

Here's a conceptual example using a custom component, such as a slider you implement yourself:

auto volumeControl = new MySliderComponent(window);

volumeControl.onValueChanged(delegate(int value) {
    auto settings = getGlobalSettings();

    settings.volume = value;                // update runtime settings
    EXT_SetSoundVolume(value);              // apply immediately
    saveGameSettings("data/settings.json"); // persist to disk
});

Project config

DVN is generally configured through DUB, but the configuration is only required if you need to build DVN, so for a VN that never touches events etc. you won't need to touch the project configuration at all.

If you're only writing scripts and assets (most VN creators), you don't need to modify dub.json at all — DVN handles everything automatically.

Example DVN dub.json:

{
	"name": "projectdvn",
	"targetType": "executable",
	"targetPath": "../../build/client",
	"targetName": "DVN",
	"dependencies": {
		"derelict-util": "~>3.0.0-beta.1",
		"dvn": "~>1.1.15"
	},
	"stringImportPaths": [
		"extensions"
	],
	"configurations": [{
		"name": "windows",
		"lflags": ["/LIBPATH:libs_derelict_sdl", "/SUBSYSTEM:windows"]
	}, {
		"name": "linux",
		"lflags": ["/LIBPATH:libs_derelict_sdl"]
	}, {
		"name": "macos",
		"lflags": ["/LIBPATH:libs_derelict_sdl"]
	}]
}

For more details about DUB configuration, dependency management, and build options, visit the official documentation at: https://code.dlang.org/

Most VN creators will never need to adjust build configuration - it's there for advanced use cases like custom modules, native extensions, or engine modification.

CSV parsing

Because DVN is written in the D programming langauge that means DVN supports a fully compliant CSV parser.

Example: (Taken from dlang.org)

import std.algorithm;
import std.array;
import std.csv;
import std.stdio;
import std.typecons;

void main()
{
    auto text = "Joe,Carpenter,300000\nFred,Blacksmith,400000\r\n";

    foreach (record; csvReader!(Tuple!(string, string, int))(text))
    {
        writefln("%s works as a %s and earns $%d per year",
                 record[0], record[1], record[2]);
    }

    // To read the same string from the file "filename.csv":

    auto file = File("filename.csv", "r");
    foreach (record;
        file.byLine.joiner("\n").csvReader!(Tuple!(string, string, int)))
    {
        writefln("%s works as a %s and earns $%d per year",
                 record[0], record[1], record[2]);
    }
}

For more details about CSV parsing in D, please consider visiting the official documentation at https://dlang.org/phobos/std_csv.html