Skip to content

Installation & GPU Setup

OpenSpace relies heavily on real-time OpenGL/Vulkan shaders, volumetric raycasting, and multi-gigabyte planetary texture streaming. Proper installation paths and discrete GPU enforcement are essential before launching your first session.

Step 1: Installation Path Rules

Extract or install OpenSpace to a non-protected root directory with full user write permissions:

  • Recommended: C:/OpenSpace-[version]/ or D:/OpenSpace-[version]/
  • Avoid: C:/Program Files/ or C:/Program Files (x86)/

Write-Permission & Path Length Traps

Windows restricts write access inside Program Files, which breaks runtime cache generation, ScriptLog.txt exports, and HTTP asset synchronization. Avoid placing OpenSpace inside deeply nested folders (such as OneDrive/Desktop/...) to prevent Windows 260-character MAX_PATH failures during SPICE and tile caching.

Step 2: Enforce Discrete GPU Usage

On laptops and multi-GPU workstations, Windows frequently assigns OpenSpace.exe to integrated graphics by default, resulting in single-digit framerates or shader compilation errors.

  1. Open Windows Settings System Display Graphics.
  2. Click Browse and select <OpenSpace_Root>/bin/OpenSpace.exe.
  3. Select Options High performance (confirming your discrete NVIDIA or AMD GPU is listed) Save.
  1. Right-click the desktop and open NVIDIA Control Panel.
  2. Navigate to 3D Settings Manage 3D settings Program Settings.
  3. Click Add, locate OpenSpace.exe, and set Preferred graphics processor to High-performance NVIDIA processor.
  4. Click Apply.

Step 3: Display Scaling & Window Configuration

High-DPI monitors (150%–200% Windows scaling) can clip the OpenSpace launcher or misalign mouse hitboxes inside the UI overlay.

  • Launcher Scaling Fix: Right-click OpenSpace.exe Properties Compatibility Change high DPI settings check Override high DPI scaling behavior and set Scaling performed by to Application.
  • Window Configuration (single.json): OpenSpace reads its viewport layout from <OpenSpace_Root>/config/single.json (or single_fisheye.json for dome setups). Edit the Size and Pos fields if you need a custom borderless or windowed resolution for screen capture or multi-monitor setups:
{
  "windows": [
    {
      "name": "OpenSpace",
      "pos": [100, 100],      // (1)!
      "size": [1920, 1080],   // (2)!
      "fullscreen": false,
      "decorated": true
    }
  ]
}
  1. Screen coordinates [X, Y] in pixels from the top-left corner of your primary display.
  2. Viewport resolution [Width, Height] in pixels.

Step 4: Editor Setup (VS Code)

Because OpenSpace scenes, profiles, and keybindings are authored in Lua (.asset) and JSON (.profile), configure VS Code before building custom content:

  1. Install the Lua extension (sumneko.lua / Lua Language Server) for syntax highlighting, bracket matching, and Lua diagnostics.
  2. Open your OpenSpace root folder (File -> Open Folder...) so you can search across built-in ${BASE}/data/assets examples while writing your own assets.
  3. Verify that your editor uses UTF-8 encoding and LF or CRLF line endings without adding rich-text formatting.