A Chrono::Vehicle YAML model specification file defines a vehicle model by referring to the Chrono::Vehicle JSON specification files of its sub-systems. It consists of the following objects:

[required] The Chrono version (chrono-version) that is compatible with the YAML model specification. This is a string of the form M.m (major.minor) or M.m.p (major-minor-patch), although only the two fields are verified for compatibility.
[required] The model object which defines JSON specification files for the vehicle sub-systems.
[optional] The terrain_json entry which names a JSON specification file for a rigid terrain.
[optional] The initial_position and initial_yaw entries which define the initial vehicle pose.
[optional] The chase_camera object which defines the run-time chase-camera settings.

Note that only model is a nested object; terrain_json, initial_position, initial_yaw, and chase_camera are specified at the top level of the file, as siblings of model.

Model specification

The model object identifies the JSON files describing the vehicle and its powertrain. The vehicle type (wheeled or tracked) is not stated in the YAML file; it is inferred from the Template field of the vehicle JSON file.

Property	Description	Type	Available Values	Required	Default
`name`	Name of the model	string	–	No	empty string
`angle_degrees`	Whether angles are specified in degrees (true) or radians (false)	boolean	–	No	`true`
`data_path`	Location of the JSON data files referenced below	object	–	No	absolute paths
`vehicle_json`	JSON file for the vehicle model	string	–	Yes	–
`engine_json`	JSON file for the engine model	string	–	Yes	–
`transmission_json`	JSON file for the transmission model	string	–	Yes	–
`tire_json`	JSON file for the tire model	string	–	Yes, for wheeled vehicles	–

The data_path key, if present, specifies the following properties:

Property	Description	Type	Available Values	Required	Default
`type`	Mode for data file location	enum	`ABSOLUTE`,`RELATIVE`	Yes	`ABSOLUTE`
`root`	Root of data files, relative to the location of this file	string	–	No	`.`

Terrain, initial pose, and chase camera

These entries are specified at the top level of the vehicle model file.

Property	Description	Type	Available Values	Required	Default
`terrain_json`	JSON file for a rigid terrain. If absent, no terrain is created.	string	–	No	no terrain
`initial_position`	Initial location of the vehicle reference frame	array[3]	–	No	[0, 0, 0]
`initial_yaw`	Initial vehicle heading, always in degrees	double	–	No	0
`chase_camera`	Run-time chase-camera settings	object	–	No	–

Note that initial_yaw is always interpreted in degrees, independent of the angle_degrees setting in model.

The chase_camera key, if present, specifies the following properties (all of which are then required):

Property	Description	Type	Available Values	Required	Default
`chassis_point`	Camera target point, in the chassis reference frame	array[3]	–	Yes	–
`chase_distance`	Initial horizontal distance between camera and target point	double	–	Yes	–
`chase_height`	Initial vertical distance between camera and target point	double	–	Yes	–

Example

Below is an example of a wheeled vehicle model configuration:

chrono-version: 10.0
 
model:
  name: Polaris
  angle_degrees: true
  
  data_path:
    type: RELATIVE
    root: "../.."
 
  vehicle_json: "vehicle/Polaris/Polaris.json"
  engine_json: "vehicle/Polaris/Polaris_EngineSimpleMap.json"
  transmission_json: "vehicle/Polaris/Polaris_AutomaticTransmissionSimpleMap.json"
  tire_json: "vehicle/Polaris/Polaris_TMeasyTire.json"
 
terrain_json: "vehicle/terrain/RigidPlane.json"
 
initial_position: [0, 0, 0.5]
initial_yaw: 0
 
chase_camera:
  chassis_point: [0, 0, 1.75]
  chase_distance: 7.0
  chase_height: 0.5

YAML schema

The YAML vehicle model specification file must follow the data/yaml/schema/vehicle_model.schema.yaml provided in the Chrono data directory:

# =============================================================================
# PROJECT CHRONO - http://projectchrono.org
#
# Copyright (c) 2025 projectchrono.org
# All rights reserved.
#
# Use of this source code is governed by a BSD-style license that can be found
# in the LICENSE file at the top level of the distribution and at
# http://projectchrono.org/license-chrono.txt.
# =============================================================================
#
# Schema for a YAML Chrono::Vehicle model specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
#
# =============================================================================
 
required: [chrono-version, model]
 
chrono-version:
  type: string
  description: Chrono version compatible with this YAML specification (M.m or M.m.p)
 
# -----------------------------------------------------------------------------
# Definitions of common Chrono types
 
vector3d: &VECTOR3D   # Specification of a ChVector3d
    type: array
    items:
        type: number
    minItems: 3
    maxItems: 3
 
# -----------------------------------------------------------------------------
# Definition of the vehicle model
 
model:
  description: |
    Definition of a Chrono::Vehicle model.
    The vehicle and its sub-systems are specified through Chrono::Vehicle JSON specification files.
    The vehicle type (wheeled or tracked) is inferred from the "Template" field of the vehicle JSON file.
  type: object
  required: [vehicle_json, engine_json, transmission_json]
  properties:
    name:
      type: string
      description: Name of the model
      default: ''
    angle_degrees:
      type: boolean
      description: Whether angles are specified in degrees (true) or radians (false)
      default: true
    data_path:
      type: object
      description: Location of the JSON data files referenced in this model specification
      required: [type]
      properties:
        type:
            type: string
            description: Mode for data file location
            enum: [ABSOLUTE, RELATIVE]
            default: ABSOLUTE
        root:
            type: string
            description: Root of data files, relative to the location of this script
            default: "."
    vehicle_json:
      description: JSON file for vehicle model specification
      type: string
    engine_json:
      description: JSON file for engine model specification
      type: string
    transmission_json:
      description: JSON file for transmission model specification
      type: string
    tire_json:
      description: JSON file for tire model specification (required for WHEELED vehicles)
      type: string
 
# Note: the following four objects are specified at the top level of the vehicle model file
#       (as siblings of the `model` object), not nested inside `model`.
 
terrain_json:
  description: JSON file for rigid terrain specification. If absent, no terrain is created.
  type: string
  default: ""
      
initial_position:
  <<: *VECTOR3D
  description: Initial vehicle position
  default: [0, 0, 0]
 
initial_yaw:
  description: Initial vehicle yaw angle, always in degrees (independent of the model `angle_degrees` setting)
  type: number
  default: 0.0
 
chase_camera:
  description: Parameters for the vehicle chase camera
  type: object
  required: [chassis_point, chase_distance, chase_height]
  properties:
    chassis_point:
      <<: *VECTOR3D
      description: Chase camera target point on chassis
    chase_distance:
      description: Initial value of the horizontal distance between camera and target point
      type: number
    chase_height:
      description: Initial value of the vertical distance between camera and target point
      type: number
    