# Projects and Scenes

Configure Oden project files, scene graph entities, project settings, application settings, and launch modes.

Last validated: 2026-05-05

Use this page when you need to understand what is stored in an Oden project, how to edit a Streamer or Player project, and where the old reference-style settings now fit.

## Project files

Oden projects are `.vproj` files using libconfig syntax. They store scenes, entities, inputs, output settings, network links, plugin paths, and project-specific view settings.

| Project | Typical owner | Common path |
| --- | --- | --- |
| Streamer project | Vehicle computer or Fleet Streamer service | `/opt/oden-streamer/oden-vehicle-config.vproj` |
| Player project | Operator station or fleet-assigned Player profile | Project-specific path chosen from **File**  **Open…​** |
| Application config | Local application instance | Windows: `%LOCALAPPDATA%\oden\oden.conf`; Linux: `$HOME/.config/oden/oden.conf` |

Prefer editing projects through the GUI. Edit `.vproj` files directly only for repeatable deployment changes that you can validate in Oden before shipping.

## Edit a Streamer service project

When Oden Fleet Streamer runs as `oden-streamer.service`, stop the service before editing the same project in the GUI.

```shell
sudo systemctl stop oden-streamer.service
sudo oden-streamer /opt/oden-streamer/oden-vehicle-config.vproj
sudo systemctl start oden-streamer.service
```

The service runs as `root`, so the project file may be owned by `root`. If saving fails, check ownership and reopen with the required permissions.

To edit a headless Streamer remotely, run Streamer with the configurator mode enabled and connect from a Player project that contains both a `Remote Streamer` entity and a `Streamer Configurator` entity. The configurator streams the Streamer GUI to the Player so the project can be edited without a monitor on the vehicle computer.

Remote configurator workflow:

1.  Start the Streamer with `--headless --configurator` and the project you want to edit.
    
2.  Start the Player and connect to the vehicle.
    
3.  Add a `Streamer Configurator` entity to the Player scene.
    
4.  Select the entity and press the connect button in its `Remote Streamer` section.
    
5.  Edit the Streamer GUI in the streamed configurator window.
    
6.  Save the Streamer project and restart the service when the edited project is used by `oden-streamer.service`.
    

> **NOTE**
> Some keyboard shortcuts may not work through the Streamer Configurator window.

## GUI areas

Top menu

Use `File` to open, save, import, and export project material. Use `Edit` to undo, redo, copy, paste, add, and delete entities. By default, `Paste Entity` replaces pasted video inputs with clone streams to the original inputs. Use Ctrl+Shift+V when you intentionally want to copy the original inputs instead. Use `Window` for fullscreen behavior. Use `Help` for license activation, license info, changelog, manual, and About.

Common menu entries:

| Menu | Use |
| --- | --- |
| File | Open, save, and reopen recent projects. Import or export scenes, cameras, and templates when part of a project should be reused. Close the current project or exit the application. |
| Edit | Cut, copy, paste, add child entities, and delete selected entities. Many actions show their current keyboard shortcut in the menu. |
| Window | Control display mode and fullscreen behavior where the current application exposes those actions. |
| Help | Open the changelog, this manual, About, license entry, license information, and license revocation actions. For license workflow details, see [Activate Licenses](../start/activate-licenses.md). |

Sidebar

`Root Entity` holds the active scene graph. `Scenes` lists scenes in the project. `Raw Recording` records runtime video and scene data for later playback or support. `Network` and `Output` appear on Streamer. `Plugins`, `Com Channels`, `Statistics`, `Project Settings`, and `Application Settings` are shared concepts. The Player also exposes Player-specific settings such as HMD options when those features are available.

3D viewport

Hold the left mouse button and use W, A, S, and D to move the viewport camera. Use Q and E to move down and up. Use the home icon or Ctrl+Q to return to the origin. Oden uses a right-handed coordinate system: `-Z` is forward, `+Y` is up, and `+X` is right. Entity positions use meters, rotations use degrees, and scale is unitless.

## Scenes and entities

A scene is a tree of entities. The root entity holds child entities such as 2D video, text, models, output alignment, webview-facing video layout, Remote Streamer, and Streamer Configurator entities. Add entities by selecting the intended parent and using `Add Child`. Drag entities in the tree to rearrange them. Parent position, rotation, and scale are applied to child entities, so an empty `Entity` is useful as a grouping node, pivot, or shared transform. For stable projects, place related siblings under a clear shared parent instead of creating deep trees only to move several items together.

Common entity choices:

| Entity | Use |
| --- | --- |
| `2D Video` | Show a video input or a received stream in a Player scene. Configure placement, size, curvature, stereo eye visibility, border, chroma key, matte key, and input source. |
| `2D Image` | Place a static image in the scene. |
| `Text` | Place labels, debug values, or operator hints in a native scene. |
| `Model` | Load and inspect a 3D model. Use collision mesh settings only when the project requires interaction or physics-like picking behavior. |
| `Flexbox` / `Flexbox Group` | Lay out child entities in rows or columns using web-style flex concepts. Use it for native multi-camera layouts when a webview is not controlling placement. |
| `Remote Streamer` | Receive video, audio, network stats, and Streamer feedback from a vehicle. Configure network links, audio receive/send, video codec expectations, reorder behavior, and stream diagnostics here. |
| `Streamer Configurator` | Open the Streamer GUI from the Player side. Useful for headless Streamer setup and service deployments. |
| `Output Alignment` | Map Streamer-side video sources into the encoded output. Use it when the Streamer output is composed from several video sources or when alignment must be controlled before encoding. |
| `External Scene` | Loads a `.vscene` file into the project. Use it when a shared scene should be imported, saved separately, or updated outside the main project file. |
| `Video Composition` | Creates one clonable texture from several video sources. Use it when several sources should be combined before another entity displays or clones them. |
| `Scene Mirror` | Mirrors the content of another scene. Use it to reuse shared scene content, such as a dashboard or common overlay, without duplicating the original entities. |

Useful entity details:

2D Image

Loads static scene graphics from `.png`, `.jpg`, or `.jpeg` files. Alpha is supported for formats that carry transparency. Convert unsupported image formats before importing them.

Text

Exposes text content, color, glow, glow size, glow color, font, font height, and resolution settings. Use it for in-scene labels and instrumentation that should stay native to Oden rather than inside a webview.

Model

Loads glTF models. Use `Clone Model` or instanced rendering when a project needs several copies of the same model. `Open` loads the model file. Environment lighting can improve reflections but increases GPU work. `Inspect Model` is for temporary inspection; changes made there are not saved back to the source asset. Collision meshes are mainly for plugin interaction and project-specific picking workflows.

External Scene

Keeps scene content in a separate `.vscene` file. Use it for version-controlled shared scenes, reusable camera rigs, or scenes that several projects import. Child entities remain editable in Oden. `Save Scene` writes the `.vscene` file, and `Auto Save` keeps the external scene updated when the parent project is saved.

Streamer Configurator

Connects a Player-side configurator window to a Streamer GUI. Use direct server address entry when discovery cannot find the Streamer. Automatic discovery works best on the same local network. Use `Bind Address` or `Bind IP` when the computer has several interfaces and the configurator should use a specific one. The configurator UI scale follows the Player-side setting, the top-right controls set maximum width and height, and the bottom-right handle resizes the streamed window.

For camera/source configuration, see [Camera Inputs](camera-inputs.md). For Player layout details, see [Player Layout](player-layout.md).

## Project settings

Project settings are saved inside the `.vproj` file. Use them for behavior that should travel with the project rather than the local computer.

Important settings:

Startup Scene

Scene opened when the project starts.

Background

Default background mode or color. Use `Default`, `Default, Only For Orbit Camera`, or `Color` when available. Set `Background Color` when the project should render against a fixed color.

Camera Eye

Which eye the monitor viewport shows when stereo/HMD output is configured.

Show Grid and Grid Height

Viewport grid display and height.

Force Feedback

Enables force feedback for supported joysticks.

Auto Video Packing

Automatically packs visible video into the encoded Streamer output. Use per-megapixel bitrate in stream settings when output resolution changes dynamically.

View

Field of view, position, rotation, project-default view, and saved states. Use `Reset View To Project Default` to return to the saved view. Use `Set View As Project Default` after positioning the viewport for the production layout. `Save Current State` records a named view state, and `Clear All Saved States` removes the saved list.

Save the project after changing project settings. For production projects, reopen the project and verify that the selected startup scene and saved view are still correct.

## Application settings

Application settings are local to the computer and application config file. Use them for display and interaction behavior that should not necessarily travel with every project file.

Window Mode

`Windowed` uses a normal resizable window. `Windowed Fullscreen` fills the screen without native fullscreen. `Fullscreen` gives the lowest display latency on one monitor. `Spanning Fullscreen` is windowed fullscreen across multiple screens.

Monitor

Selects the display used by fullscreen and windowed-fullscreen modes when several monitors are attached.

Hide GUI on Startup

Starts the Player with commissioning controls hidden. The GUI can still be toggled with the configured shortcut, normally Ctrl+H.

Inhibit Mouse Look

Prevents mouse motion from moving the viewport camera. Enable this for operator stations where the mouse is part of an external UI.

VSync

Disable VSync for lowest latency unless a project-specific display setup needs it.

MSAA

Multisample anti-aliasing. Enable only when the visual quality benefit is worth the extra GPU cost.

Rendering Mode

Selects display projection behavior such as single projection, separate projection, spanning fullscreen, cylindrical, or dome-specific projection modes where available. Use normal single-display modes unless the deployment has a measured multi-projector or dome requirement.

Auto Template

Path to a `.vtemplate` file applied to loaded projects. Use it for repeatable deployment defaults, not for ad-hoc project edits.

Camera Calibration

Path to stored `.camera` calibration presets. The path may contain environment variables and must end with a slash, for example `C:/dev/Cameras/`.

Shrink View When GUI Visible

When enabled, Oden uses only the visible viewport while the GUI is shown. When disabled, Oden uses the full window as the viewport even behind the GUI, so entities do not move when the GUI is hidden.

Keyboard shortcuts

Many menu actions show their shortcut in the menu. Keep shortcut changes documented for operator stations. Each shortcut uses a key plus optional Ctrl, Shift, Alt, or Super modifiers. Modifiers can be combined. Set a shortcut to `[Inactive]` when the action must not be available from the keyboard.

Additional local behavior settings can include scroll mode, inverted mouse, GUI color mode, full project files, no prompt on exit, and only-show-exit-dialog. Use these as deployment controls for the local workstation, not as project behavior that should follow the `.vproj` to another machine.

## Local files and directories

Application config, licenses, dome data, and global plugins are local to the machine. Do not assume they travel with a `.vproj` project file.

| Data | Typical location |
| --- | --- |
| Application config | Windows: `%LOCALAPPDATA%\oden\oden.conf`; Linux: `$HOME/.config/oden/oden.conf` |
| License data | Stored under the per-application Oden data root for the activated user. Typical roots are Windows `C:\ProgramData\OdenVR\`, `C:\ProgramData\Oden Streamer\`, `C:\ProgramData\Oden Dome Player\`; Linux `$HOME/.config/oden/OdenVR/`, `$HOME/.config/oden/Oden_Streamer/`, `$HOME/.config/oden/Oden_Dome_Player/`. For root-run services, activate with `sudo` so the service account can read `key.conf` and `license2.lic`. |
| Project plugins | Project file directory or configured `Project Plugins Path`. |
| Global plugins | Directory beside the Player or Streamer executable. |
| Dome and calibration assets | Project-specific path or configured calibration preset directory. |

## Launch modes

Use command-line flags in service files, startup scripts, or troubleshooting sessions.

| Flag | Use |
| --- | --- |
| `--headless` | Linux Streamer mode where the GUI is not rendered. Use it for services, vehicle computers, and embedded platforms. |
| `--configurator` | Allows a Player `Streamer Configurator` entity to connect to and configure a Streamer even without an active Remote Streamer connection. |
| `--windowless` | Runs the Player with the window hidden. Toggle with Ctrl+Shift+H. |
| `--multiple-streamers` | Allows more than one Streamer instance on the same computer. Use only when ports, project files, licenses, and capture devices are intentionally separated. |
| `--plugin-param <key> <value>` | Passes plugin-specific parameters from the launcher instead of storing them in the project. |

For service deployment, see [Deployment](../operate/deployment.md).