ScenarioConfig

The public configuration contract, shared by Studio, the API and automation. This page explains its shape and its rules. The complete field list is generated separately, because a hand-maintained copy of 430 fields would be wrong within a month.

Required sections#

A scenario must carry all of these:

schema_version
scenario_id
scenario_version
master_seed
scene
spawn
camera
environment
capture
annotations
output

Adopted optional sections#

Beyond the required set, the contract also accepts:

animation_randomization
dependency_rules
generation
material_randomization
name
scenario_hash
scene_manifest_hash
sensor

Why unknown fields fail#

The JSON Schema stays permissive enough for the contract to evolve. NameFrame does not treat that permissiveness as licence to accept arbitrary input.

The compiler keeps an explicit field ownership registry. A field that is not in it fails validation rather than being silently dropped, which is the difference between a typo you find in one second and a run that quietly ignored the setting you cared about.

The current registry holds 430 field definitions: 426 supported, 3 unsupported and 1 deprecated. The largest owners are:

spawn                  232 fields
camera                  41 fields
performance             30 fields
environment             27 fields
viewpoint_validation    23 fields
sensor                  16 fields
render                  16 fields
contract                 8 fields

Consumption is checked, not assumed#

Registering a field is not the same as using it. The compiler records which fields were actually consumed during compilation, so a public field that stops being read during a refactor is detected rather than becoming a setting that exists and does nothing.

This is the mechanism behind a claim made elsewhere in this documentation: if a configuration option is public and supported, something reads it.

The full field reference#

Generated from the registry, the schema and the compiler's consumption owners rather than maintained by hand. See the recipe reference for the sections in their authoring form, and architecture for how a scenario becomes a CaptureJob.