Where your data lives

Korall Engineering™ stores everything it remembers — settings, identities, keys, scenes, logs — under one directory per application.

The organization segment is plain ASCII and is the same for every application. The <app> segment is the base id of the application, in lower case, for a node app and for a standalone app alike:

~/.local/share/Korall Engineering/
├── agent/
├── construct/
├── hub/
└── remote/

Each application keeps its own directory, so running two of them never mixes their data.

Pro Tip

Every application resolves this once, at startup, and uses the same answer for the rest of the run. If you need it somewhere else — a portable install, a test rig, a second isolated instance — set it at launch rather than moving the directory afterwards.

Debug builds

A debug build does not use the platform folder. It keeps its data in data/<app>/ beside its own program, in <binary dir>/data/<app>, so two development builds never share one configuration. When the folder of the program is not writable, the debug build falls back to the platform folder above and prints a warning that says so. Pass --base-dir <path> to choose the folder yourself.

Settings and configuration files

A release build keeps the settings of an application in the settings store of the platform, not in the data folder:

Some applications also keep configuration files of their own, for example a library of color gradients. These files go in the configuration folder:

A debug build, and a run with --base-dir, keeps everything in its data folder. The settings are in settings.ini there, and the configuration files are beside it.

What is in the directory

These folders hold the evidence that a bug report or a crash report is made from. See Diagnostic reports.

On Windows, an installer that sets up Windows Error Reporting for the app keeps its crash dumps in %LOCALAPPDATA%\Korall Engineering\crash-dumps\, not in the folder that every program shares. The app deletes a dump from there once the report that holds it is sent or deleted.

If you upgraded and your data looks missing

It is not missing. It is in the directory beside the one you are looking at.

This section is for an edition whose organization name carries a mark, such as ™. Older versions of such an edition stored data under a folder named with the mark, Korall Engineering™, because the brand name was used directly as a directory name. That turned out to be a bad idea:

• Windows code pages that cannot represent ™ mangled the path.
• Different parts of the program disagreed about whether the symbol was there, so the same machine could end up with two data directories and no indication which one was live.

Current versions use the plain ASCII name, Korall Engineering, everywhere, always. An edition whose name never carried a mark had no old directory, and never shows the message below.

What the upgrade does — and does not — do

The first time a new version starts on a machine that has an old directory, it prints this, once:

Data location changed. This version stores data in
    /home/you/.local/share/Korall Engineering/hub
An older directory exists at
    /home/you/.local/share/Korall Engineering™/hub
and this version does NOT read it. Nothing was moved, copied or deleted — the
old directory is untouched and can be removed by hand once you are sure you do
not want it.

That is the whole behaviour, and each part of it is deliberate:

Nothing is migrated automatically, on purpose. An automatic move is a one-way operation on data we cannot verify — identities and keys included — and if it went wrong there would be nothing left to go back to. Leaving the old directory untouched means the worst case is that you copy files across yourself.

Moving your old data across

Stop the application first, then copy the contents of the old directory into the new one:

# Linux / macOS
cp -a ~/.local/share/'Korall Engineering™'/hub/. ~/.local/share/Korall Engineering/hub/

# Windows PowerShell
Copy-Item "$env:LOCALAPPDATA\Korall Engineering™\hub\*" "$env:LOCALAPPDATA\Korall Engineering\hub\" -Recurse

Copy rather than move until you have confirmed the application starts and your identities are present. Once you are satisfied, delete the old directory by hand.

When the message does not appear

It only appears when there is something to say — when an old directory exists and the new one does not yet. You will not see it on a fresh install, on a second run, or if you have already got a new-style directory. Seeing it once and never again is correct.

Non-ASCII paths generally

Your own paths can contain anything your filesystem allows — accented characters, CJK, emoji in a scene filename. The restriction above was only ever about the directory we create from our own brand name, and it is fixed by us using ASCII, not by restricting you.

Log output is UTF-8 on every platform. If you redirect a log to a file and see mangled characters in a terminal, check the terminal's encoding before assuming the file is wrong — a terminal shows you its own code page's rendering, not the bytes that were written.