Configuration

Solarxy reads two separate configuration files. They do different jobs and live in different places:

File	Scope	Lives in	Edited by
`solarxy.toml`	Per-project policy - validation rules, triangle budgets, filename classification, review sidecar location	Your repository (checked into version control)	Hand-written; shared by the whole team
`config.toml`	Per-user preferences - window size, theme, default view settings, recent files, dock layout	A per-OS application-data directory	The GUI (sidebar + Preferences modal); hand-editing optional

Project configuration: solarxy.toml
User preferences: config.toml

The nine validation checks and the in-viewport validation overlay have moved to their own page: see Validation Reference.

Project configuration: `solarxy.toml`

solarxy.toml is the per-project policy file. It controls validation - which checks run, the numeric thresholds they use, the per-category triangle budgets, and how a model's filename maps to a budget category. Studios check it into version control so every developer, and every CI run, validates against the same gates.

It is read by:

solarxy-cli --mode analyze (single-file analysis and the interactive TUI)
solarxy-cli --mode analyze --paths … (batch validation - see CI/CD Integration)
The GUI's validation overlay (Shift+V) and the Properties panel's Validation section

A solarxy.toml is entirely optional. With no config file present, Solarxy uses the built-in defaults documented below.

Discovery order

flowchart TD
    classDef hit fill:#1F2430,stroke:#7FD962,color:#7FD962
    classDef step fill:#1F2430,stroke:#5C6773,color:#CCCAC2
    classDef fallback fill:#1F2430,stroke:#FFC44C,color:#FFC44C
    classDef start fill:#33415E,stroke:#FFC44C,color:#FFC44C

    Start[Resolve solarxy.toml]:::start
    Start --> S1{--config PATH?}
    S1 -->|yes| L1[Load that file<br/>error if missing]:::hit
    S1 -->|no| S2{$SOLARXY_CONFIG?}
    S2 -->|yes| L2[Load env path<br/>error if missing]:::hit
    S2 -->|no| S3{solarxy.toml<br/>in start dir?}
    S3 -->|yes| L3[Load it]:::hit
    S3 -->|no| S4[Walk parents<br/>up to .git or<br/>20 levels]:::step
    S4 -->|found| L4[Load nearest]:::hit
    S4 -->|not found| F[Use built-in defaults]:::fallback

The four-step priority ladder. For --paths runs the start directory is the current working directory, not each asset's directory.

When you don't pass --config <PATH> explicitly, Solarxy searches for a solarxy.toml in this order:

--config <PATH> - an explicit path. Errors if the file is missing.
$SOLARXY_CONFIG environment variable - an absolute or relative path. Errors if the file is missing.
solarxy.toml in the start directory.
Walk parent directories from the start directory upward until one contains a .git/ directory (the repository root) or the filesystem root is reached - capped at 20 levels so the search stays bounded on large monorepos.
If nothing is found, the built-in ProjectConfig defaults are used.

The start directory depends on how Solarxy was invoked:

Invocation	Start directory
`solarxy-cli --mode analyze -m <model>` (single file)	The model file's parent directory
`solarxy-cli --mode analyze --paths …` (batch validation)	The current working directory

For batch validation, run solarxy-cli from your repository root (or pass --config) so discovery resolves the config you expect.

The resolved config path and a SHA-256 of its bytes are recorded in the batch validation run report, so you can prove exactly which policy validated which assets.

Editor schema support

A JSON Schema for solarxy.toml ships in the repo at schemas/solarxy-config.v1.json. Editors that honour $schema (VS Code with Even Better TOML, JetBrains IDEs, taplo) give you autocomplete and inline error highlighting. Add this as the first non-blank line of your solarxy.toml:

#:schema https://raw.githubusercontent.com/marko-koljancic/solarxy/main/schemas/solarxy-config.v1.json

The schema is generated from the canonical Rust types via schemars; regeneration steps are in schemas/README.md.

Annotated example

Every section is optional - omit any section or key and its defaults apply.

#:schema https://raw.githubusercontent.com/marko-koljancic/solarxy/main/schemas/solarxy-config.v1.json

format_version = 1

# Per-category triangle budgets. A model is classified into one category
# (see [[filenames.rules]] below) and checked against that budget.
[budgets]
hero        = 100000
prop        = 20000
environment = 50000
default     = 30000

# Per-check toggles. All default to true except allow_open_mesh.
[validation]
normal_mismatch      = true
flipped_normals      = true
non_manifold_edges   = true
triangle_budget      = true
allow_open_mesh      = false   # inverse modifier - see the table below
degenerate_triangles = true
material_refs        = true
uv_presence          = true
index_buffer         = true

# Numeric knobs read by some checks.
[thresholds]
triangle_budget_tolerance_percent = 20.0
flipped_normal_dot                = -0.5

# Map filename patterns to budget categories. First matching rule wins;
# unmatched files fall back to the `default` category.
[[filenames.rules]]
pattern  = "^hero_"
category = "hero"

[[filenames.rules]]
pattern  = "^env_"
category = "environment"

# Project-level review-system settings.
[review]
sidecar_dir = ".solarxy"

solarxy.toml field reference

Section / key	Type	Default	Purpose
`format_version`	integer	`1`	Schema version. A config written by a newer Solarxy than the one reading it loads on a best-effort basis with a `tracing::warn!`.
`[budgets]`	table	-	Per-category triangle budgets.
`budgets.hero`	integer	`100000`	Budget for `hero`-category assets.
`budgets.prop`	integer	`20000`	Budget for `prop`-category assets.
`budgets.environment`	integer	`50000`	Budget for `environment`-category assets.
`budgets.default`	integer	`30000`	Budget for assets that match no `[[filenames.rules]]`.
`[validation]`	table	-	Per-check on/off toggles - see Validation checks.
`[thresholds]`	table	-	Numeric knobs for the checks that take one.
`thresholds.triangle_budget_tolerance_percent`	float	`20.0`	The warning-to-error boundary for `triangle_budget`: any triangle count over budget warns; a count above `budget × (1 + tolerance%)` is an error.
`thresholds.flipped_normal_dot`	float	`-0.5`	Dot-product cutoff for the `flipped_normals` check - a triangle is flagged when its averaged vertex normal dots below this value against the geometric (winding-derived) normal.
`[[filenames.rules]]`	array of tables	empty	Ordered regex rules. Each rule has `pattern` (a regex matched against the filename only, not the full path) and `category` (`hero`, `prop`, `environment`, or `default`). First match wins.
`[review]`	table	-	Project-level Review System settings.
`review.sidecar_dir`	string	(none)	Override directory for `.solarxy-review.json` sidecars. A relative path resolves against the model's parent directory; an absolute path is used as-is. When unset, sidecars sit next to their model.

Strict parsing

solarxy.toml is parsed strictly - every section uses deny_unknown_fields. A typo doesn't get silently ignored; it hard-fails with a line and column reference. When the unknown key is close to a real one (Jaro-Winkler similarity ≥ 0.75), the error includes a "did you mean?" suggestion:

solarxy.toml:14:5: unknown field `flipped_normal_dott` (did you mean 'flipped_normal_dot'?)

This catches mistakes at load time rather than letting a misspelled rule quietly do nothing.

User preferences: `config.toml`

config.toml holds per-user GUI preferences: window size, MSAA, theme, the default view/render/lighting settings, recent files, the dock layout, and review-author identity. It is personal - not checked into version control, not shared.

You rarely need to edit this file by hand; the GUI manages it. It is documented here for completeness and for the occasional manual fix.

Where it lives

The path follows each platform's standard application-data convention:

OS	Path
macOS	`~/Library/Application Support/solarxy/config.toml`
Linux	`~/.config/solarxy/config.toml`
Windows	`%APPDATA%\solarxy\config.toml` (typically `C:\Users\<User>\AppData\Roaming\solarxy\config.toml`)

The Preferences modal's Startup tab displays the exact path and has an Open config file button that opens it in your default editor.

How to edit it

Three surfaces write to config.toml, each authoritative for a different slice (see the Interface page for the full breakdown):

The sidebar + Edit → Save View Settings as Default. Tune display, rendering, post-processing and lighting live, then persist the current state as the launch default from the Edit menu.
The Preferences modal (Edit → Preferences…, Ctrl/⌘+,) - startup-only fields (window size, MSAA), the theme, custom backgrounds, the reviewer name, recent-files capacity, and updater behaviour.
Direct TOML editing - open the file from the Preferences modal's Startup tab and edit it in any text editor.

config.toml section reference

config.toml mirrors the Preferences struct. Every section is optional - omitting one fills it from defaults.

Section	Holds
`config_version`	Schema version (currently `1`); reserved for future migrations.
`[display]`	Background, view mode, normals mode, grid / axis-gizmo / local-axes toggles, bloom & SSAO toggles, IBL mode, tone-mapping mode, exposure, turntable state + RPM, inspection mode, and the texel-density target.
`[rendering]`	Wireframe line weight, MSAA sample count (`1`, `2`, or `4`; default `4`), shadow map size (default `2048`).
`[lighting]`	Light-lock state.
`[window]`	Window width (`640`-`7680`, default `1280`) and height (`480`-`4320`, default `720`). Clamped to range on load.
`[history]`	`recent_files` - the recent-files list, capped by `ui.max_recent_files`.
`[ui]`	`max_recent_files` (default `20`, hard cap `50`), `status_bar_visible` (default `true`), `theme` (`Ayu Mirage Dark` or `Ayu Mirage Light`).
`[updater]`	`check_on_launch` (default `false`), `channel` (`Stable` or `Prerelease`).
`[review]`	`author` - the display name written onto new review annotations; unset ⇒ anonymous. `panel_open` - whether the Review Panel is open at launch.
`[dock]`	`last_layout_json` (the dock layout auto-saved on quit) and `saved_layout_json` (the snapshot written by `Layout → Save Layout`). Both are JSON-serialized `egui_dock` states.
`[view]`	`custom_backgrounds` - your user-defined background registry - plus `next_custom_id`, the id allocator.

Robustness

config.toml is forgiving - unlike solarxy.toml, it does not use strict parsing:

Every section is optional. Older config files upgrade cleanly when a new Solarxy version adds a section.
Unknown fields and unknown sections are ignored (forward-compatible) - a config written by a newer Solarxy loads without error in an older build.
An invalid rendering.msaa_sample_count (anything other than 1, 2, or 4) is rejected with a tracing::warn! and falls back to 4.
Window dimensions are clamped to the supported range on load.
Corrupt TOML triggers a tracing::warn! and the whole file falls back to defaults - the file is not overwritten until you explicitly save.
A corrupt or schema-incompatible [dock] layout blob falls back silently to the default layout (with a tracing::debug! line); the rest of preferences load normally.

To reset everything, delete config.toml - Solarxy recreates it on the next save. See Troubleshooting → Config reset.

See also: CLI Reference · CI/CD Integration · Review System · User Guide · Troubleshooting

Solarxy - A lightweight, cross-platform 3D model viewer and validator built with Rust and wgpu.

GitHub Repository · Releases & Downloads

Solarxy Wiki

Getting Started

Tutorials

Using Solarxy

Reference

Help

Project

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Configuration

Configuration

Project configuration: `solarxy.toml`

Discovery order

Editor schema support

Annotated example

solarxy.toml field reference

Strict parsing

User preferences: `config.toml`

Where it lives

How to edit it

config.toml section reference

Robustness

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Configuration

Configuration

Project configuration: solarxy.toml

Discovery order

Editor schema support

Annotated example

solarxy.toml field reference

Strict parsing

User preferences: config.toml

Where it lives

How to edit it

config.toml section reference

Robustness

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Project configuration: `solarxy.toml`

User preferences: `config.toml`