Skip to content

Profiles & Keybindings

A Profile (.profile JSON file) defines everything OpenSpace loads at startup: which .asset files are enabled, the initial camera position, starting simulation time, and custom hotkeys.

Creating & Editing Show Profiles

Always clone a built-in profile into ${USER}/data/profiles/ rather than editing default profiles inside ${BASE}.

  1. Launch the OpenSpace Launcher and click Edit next to a base profile (such as default or messenger), or select New Profile.
  2. Save the profile into your ${USER}/data/profiles/ directory so it persists across OpenSpace updates.

Screenshot Placeholder: profile-editor-overview.png

  • Crop: Capture the Profile Editor window showing the main section list.
  • Callouts: (1) Assets list (adding/removing .asset modules), (2) Time & Camera startup state, (3) Actions & Keybindings buttons, (4) Save location indicator (${USER}/data/profiles).

Actions & Custom Keybindings

In OpenSpace, keyboard shortcuts do not trigger raw Lua directly—they trigger named Actions, which in turn execute Lua scripts.

Step 1: Create an Action

  1. Inside the Profile Editor, open Actions Add Action.
  2. Assign a unique Identifier (e.g., custom.toggle_earth_labels), a UI Name, a GUI Path (e.g., /Custom Show/Labels), and paste the Lua command(s) to execute.
  3. Toggle Local / Sync depending on whether the action should broadcast across multi-node cluster displays.

Step 2: Bind the Action to a Key

  1. Open Keybindings in the Profile Editor and click Add Keybinding.
  2. Press the desired key combination (e.g., Shift+L) and select your Action's Identifier from the dropdown.

Overriding Default Keybindings Safely

Built-in profiles load default hotkeys from ${BASE}/data/assets/base_keybindings.asset. If you want to remap or disable factory keys (for example, preventing accidental Spacebar pauses or R resets during a live show):

  • Method A (Profile Override): Bind a new Action (or an empty no-op Action) to the same key inside your .profile. Profile keybindings load after base_keybindings.asset and take priority.
  • Method B (User Asset Override): Copy base_keybindings.asset into ${USER}/data/assets/base_keybindings.asset and edit the openspace.keybinding.setKeyBinding(...) entries directly. Because OpenSpace resolves ${USER}/data/assets/ before ${BASE}/data/assets/, your copy overrides the default cleanly without touching factory files.

Avoid Loopback Key Conflicts

When chaining Actions or creating custom keybindings, never bind a key to a Lua script that simulates pressing that same key (openspace.keybinding...), which creates an infinite execution loop.