Profile Syntax

A .profiles file is a JSON file with a predefined set of sections that can be used. Extra keys are silently ignored.

These files are not intended to be edited by hand. The profile editor GUI that launches with OpenSpace should be used to create or edit a profile. The editor provides complete control over every aspect of the file. However, this document can be a useful reference guide for an advanced user who wants to edit a profile manually or via some kind of script automation.

Sections

The supported sections are: version, 'modules, meta, assets, properties, keybindings, time, delta_times, camera, mark_nodes, and additional_scripts. These sections have to be keys of the root JSON object. Each of the sections is described below. italic values are JSON types, monospaced values are valid key names, optional denotes keys that do not have to be present.

Version

Used to specify the version number of the profile’s format. Type: object Children:

  • major (number): Describes the major version of the profile

  • minor (number): Describes the minor version of the profile

Modules

This section is intended to be used only for a module that needs to be running to ensure functionality. Each value specifies an OpenSpace module whose load status will be checked. This can be used to perform an OpenSpace action if a module is loaded or is not loaded. These actions are optional; normally only one command would be used. Type: object Children:

  • name (string): The name of the module that is to be checked

  • loadedInstruction (string) optional: The Lua command that is executed when the module is present

  • notLoadedInstruction (string) optional: The Lua command that is executed when the module is not present

Assets

Used to load assets. Each value specifies an OpenSpace asset that will be loaded Type: array of strings

Properties

This section sets specific property values at the time the profile is loaded. Each entry specifies a property and the value to set it. Type: object Children:

  • type (string): Denotes the Lua function that should be called to set the property. Must be either setPropertyValue or setPropertyValueSingle

  • name (string): The fully qualified identifier of the Property

  • value (string): The value that is to be set; this will be used as is for the Lua script, so if this is a string, it has to include escaped quote characters \"

Keybindings

Used to set custom keybindings. Each value specifies the necessary elements in the required order. Note that the Lua command at the end may be a long list of commands (separated by ; for example), and may contain one or more tab characters which will not be confused with the delimiters between the arguments. Type: object Children:

  • key (string): The key + modifier that the keybind should be bound to

  • documentation (string): A textual description of what the keybind should do

  • name (string): A human-readable name for the keybind

  • gui_path (string): The location in the GUI where the keybind should be stored

  • is_local (boolean): If true the results of the keybind action will not be transmitted to connected peers

  • script (string): The script to be executed

Time

This specifies the time to be set at startup. Type: object Children:

  • type (string): Denotes the type of Time setting, must be either absolute or relative

  • value (string): The value of the time, if type is absolute, this is an ISO time string, for example 2018-10-30T23:00:00.500 otherwise a time relative to the time when the application starts, for example -1d for rewinding one day

Camera

Used to set the camera position at startup. There are two types of camera position initializations: setNavigationState or goToGeo. Type: object Children:

  • type (string): Determines the type of the camera specification. Must be setNavigationState or goToGeo. The choice of type determines the remaining types

setNavigationState

  • anchor (string): The name of the scene graph node used as the anchor for the camera

  • aim (string) optional : The name of the scene graph node used as the aim for the camera

  • frame (string): The name of the reference frame in which the camera is specified

  • position (object): Provides the location of the camera, must have the keys x, y, and z, all number s

  • up (object) optional: Sets the up vector of the camera. If it exists it must have the keys x, y, and z, all number s

  • yaw (number) optional: Sets the yaw, which is an additional rotation around the view direction

  • pitch (number) optional: Sets the pitch of the camera, that is an additional rotation up or down

goToGeo

  • anchor (string): The name of the scene graph node used as the anchor for the camera. Must be a planetary body

  • latitude (number): The latitude of the camera location (in degrees)

  • longitude (number): The longitude of the camera location (in degrees)

  • altitude (number) optional: The height of the camera in meters

Mark Nodes

Used to mark interesting nodes at startup. Type: array of strings

AdditionalScripts

Additional Lua scripts that should be executed when the profile is loaded. This should not be used to execute scripts that could be handled through one of the other sections. Type: array of strings

Meta

Meta information describing the profile; who made it, etc Type: object Children:

  • name (string) optional: A descriptive name of the profile

  • version (string) optional: A content-based version; not to be mixed up with the other Version parameter which describes the format of the profile file

  • description (string) optional: A description for the profile that tells the user what to expect

  • author (string) optional: The name of the author or authors of the profile

  • url (string) optional: A URL that describes where the data comes from, points to the personal homepage of the authors, etc

  • license (string) optional: The license under which this profile can be used

Delta Times (a.k.a. ‘Simulation Time Increments’)

Array of time increments in units of simulation seconds per wall-clock seconds. These provide ways to speed up the simulation time. By default, these map to the number keys 1 through 0, then SHIFT+ 1 through 0, and finally CTRL+ 1 through 0. However, they can also be re-mapped to other keys. Type: array of integers

Example

The following file is the NewHorizons .scene file converted to .profile format:

{
  "version": { "major": 22, "minor": 21 },
  "meta": {
    "name": "name",
    "version": "version",
    "description": "description",
    "author": "author",
    "url": "url",
    "license": "license"
  },
  "modules": [
    { "name": "abc-module" },
    { "name": "def-module" },
    { "name": "ghi-module" }
  ],
  "assets": [
    "scene/solarsystem/planets/earth/earth",
    "scene/solarsystem/planets/earth/satellites/satellites",
    "folder1/folder2/asset",
    "folder3/folder4/asset2",
    "folder5/folder6/asset3"
  ],
  "properties": [
    {
      "type": "setPropertyValue",
      "name": "{earth_satellites}.Renderable.Enabled",
      "value": "false"
    },
    {
      "type": "setPropertyValue",
      "name": "property_name_1",
      "value": "property_value_1"
    },
    {
      "type": "setPropertyValue",
      "name": "property_name_2",
      "value": "property_value_2"
    },
    {
      "type": "setPropertyValue",
      "name": "property_name_3",
      "value": "property_value_3"
    },
    {
      "type": "setPropertyValueSingle",
      "name": "property_name_4",
      "value": "property_value_4"
    },
    {
      "type": "setPropertyValueSingle",
      "name": "property_name_5",
      "value": "property_value_5"
    },
    {
      "type": "setPropertyValueSingle",
      "name": "property_name_6",
      "value": "property_value_6"
    }
  ],
  "delta_times": [
    1.0,
    5.0,
    30.0,
    60.0,
    300.0,
    1800.0,
    3600.0,
    43200.0,
    86400.0,
    604800.0,
    1209600.0,
    2592000.0,
    5184000.0,
    7776000.0,
    15552000.0,
    31536000.0,
    63072000.0,
    157680000.0,
    315360000.0,
    630720000.0,
    1250000000.0
  ],
  "keybindings": [
    {
      "key": "T",
      "documentation": "T documentation",
      "name": "T name",
      "gui_path": "T Gui-Path",
      "is_local": true,
      "script": "T script"
    },
    {
      "key": "U",
      "documentation": "U documentation",
      "name": "U name",
      "gui_path": "U Gui-Path",
      "is_local": false,
      "script": "U script"
    },
    {
      "key": "CTRL+V",
      "documentation": "CTRL+V documentation",
      "name": "CTRL+V name",
      "gui_path": "CTRL+V Gui-Path",
      "is_local": false,
      "script": "CTRL+V script"
    }
  ],
  "time": {
    "type": "relative",
    "value": "-1d"
  },
  "camera": {
    "type": "goToGeo",
    "anchor": "Earth",
    "latitude": 58.5877,
    "longitude": 16.1924,
    "altitude": 2.0e+07
  },
  "mark_nodes": [
    "Earth", "Mars", "Moon", "Sun"
  ],
  "additional_scripts": [
    "script-1",
    "script-2",
    "script-3"
  ]
}