Skip to content

Workspace Architecture (${BASE} vs. ${USER})

The most important architectural rule in OpenSpace is never modifying files inside the core installation directory. OpenSpace separates built-in application files (${BASE}) from your custom assets, profiles, and cached downloads (${USER}) so you can upgrade OpenSpace cleanly without losing work.

Directory Map

C:/OpenSpace/                     <-- ${BASE} (Core installation; overwritten on updates)
├── bin/                          <-- OpenSpace.exe & DLL dependencies
├── config/                       <-- Window configs (single.json, single_fisheye.json)
├── data/
│   ├── assets/                   <-- Built-in solar system & mission .asset files (Read-Only Reference)
│   └── profiles/                 <-- Default factory .profile files
├── logs/
│   ├── log.html                  <-- Runtime warnings & Lua/SPICE error diagnostics
│   └── ScriptLog.txt             <-- Live log of every Lua command triggered by UI actions
└── openspace.cfg                 <-- Master path routing configuration

D:/OpenSpace_User/                <-- ${USER} (Your persistent workspace; safe across updates)
├── cache/                        <-- Downloaded HTTP/SPICE/GlobeBrowsing tile caches
├── config/                       <-- Custom window layouts
├── data/
│   ├── assets/                   <-- Your custom .asset files, 3D models, & local .bsp kernels
│   └── profiles/                 <-- Your custom show .profile files
├── recordings/                   <-- Saved session recordings & exported frame sequences
└── screenshots/                  <-- Captured PNG/JPG screenshots

Configuring ${USER} in openspace.cfg

By default, OpenSpace stores user data inside the installation folder or your Windows Documents directory. Point ${USER} to a dedicated, version-controlled or backed-up folder by editing openspace.cfg at the root of your installation:

Paths = {
    BASE = "${BIN}/..",
    USER = "D:/OpenSpace_User",          -- (1)!
    DATA = "${BASE}/data",
    ASSETS = "${DATA}/assets",
    PROFILES = "${DATA}/profiles",
    USER_ASSETS = "${USER}/data/assets", -- (2)!
    USER_PROFILES = "${USER}/data/profiles",
    CACHE = "${USER}/cache",
    LOGS = "${BASE}/logs",
    RECORDINGS = "${USER}/recordings",
    SCREENSHOTS = "${USER}/screenshots"
}
  1. Dedicated User Root: Always use forward slashes (/) in openspace.cfg and .asset files. Windows backslashes (\) act as escape sequences in Lua strings and will break path resolution.
  2. Automatic Asset Discovery: Any .asset file placed inside ${USER}/data/assets/ becomes automatically selectable in the OpenSpace Profile Editor alongside built-in assets.

How Overrides Work

When OpenSpace resolves a relative asset path (for example, scene/solarsystem/planets/earth/earth), it checks ${USER}/data/assets/ first before falling back to ${BASE}/data/assets/. This allows you to override or extend built-in assets without editing factory files.

Safe Workspace Syncing (robocopy)

When managing multiple show machines (such as a planetarium control console and production workstation), use Windows robocopy to mirror your ${USER}/data directory safely without overwriting machine-specific cache folders:

@echo off
set SOURCE="D:\OpenSpace_User\data"
set DEST="\\SHOW-PC\OpenSpace_User\data"

robocopy %SOURCE% %DEST% /MIR /Z /R:3 /W:5 /XD cache logs
pause
Flag Breakdown
  • /MIR: Mirrors the directory tree (adds new/updated files and deletes removed ones at the destination).
  • /Z: Copies files in restartable mode in case of network interruption.
  • /R:3 /W:5: Retries failed locks 3 times with a 5-second wait.
  • /XD cache logs: Excludes heavy local tile caches and machine-specific runtime logs.