createAsset

Create new asset

Since R2025a

Syntax

asset = createAsset(project,assetPath,assetType)

Description

asset = createAsset(project,assetPath,assetType) creates an asset of the specified asset type at the specified path relative to the Asset folder of the specified project. For example, customCar = createAsset(prj,"Vehicles/CustomCar.rrvehicle","VehicleAsset") creates the object customCar for the asset CustomCar.rrvehicle in the project prj and assigns it the asset type "VehicleAsset". You can use asset objects to modify asset attributes, represent actors in the scenario, and modify actor behavior during simulation.

When you create a VehicleAsset or CharacterAsset with createAsset, RoadRunner creates a placeholder 3D model that you can use in your scenario. To learn more about placeholder models for vehicles and characters, see Vehicle Assets (RoadRunner Scenario) and Character Assets (RoadRunner Scenario), respectively.

Examples

Create New Vehicle Asset

Use the createAsset function to create a new VehicleAsset object in your RoadRunner project.

Create a roadrunner object, specifying the path to an existing project. For example, this code shows the path to a project, on a Windows^® machine, located at "C:\RR\MyProject". This code assumes that RoadRunner is installed in the default location, and returns an object, rrApp, that provides functions for performing basic tasks such as opening, closing, and saving scenes and projects.

rrApp = roadrunner(ProjectFolder="C:\RR\MyProject");

Note

If you are opening RoadRunner from MATLAB^® for the first time, or if you have changed the RoadRunner installation location since you last opened it from MATLAB, you can use the roadrunnerSetup function to specify new default project and installation folders to use when opening RoadRunner. You can save these folders between MATLAB sessions by selecting the Across MATLAB sessions option from the corresponding drop down.

Open an existing scene in RoadRunner by using the openScene function, specifying the roadrunner object rrApp and the filename of the specific scene that you want to open. Then, use the newScenario function to create a new scenario.

openScene(rrApp,"ScenarioBasic.rrscene")
newScenario(rrApp)

Create an object for the RoadRunner authoring API, rrApi, that references the object for the current RoadRunner instance rrApp. The rrApi object enables you to programmatically author scenarios, such as by adding and modifying actors and logic components, using MATLAB.

rrApi = roadrunnerAPI(rrApp);

Extract the object for your scenario from the Scenario property of the authoring API object rrApi. The extracted Scenario object enables you to specify the scenario in which to add scenario components such as actors and logic.

scnro = rrApi.Scenario;

Extract the object for your RoadRunner project from the Project property of the authoring API object rrApi. The extracted Project object enables you to specify the project folder for the current RoadRunner session from which to retrieve asset objects. You can use the asset objects to assign assets to actors in your scenario.

prj = rrApi.Project;

Use the createAsset function to create a new VehicleAsset object, customCar, in the project prj by specifying the relative path for the new asset as "Vehicles/CustomCar.rrvehicle" and the asset type as "VehicleAsset". You can use asset objects to modify asset attributes, represent actors in the scenario, and modify actor behavior during simulation.

customCar = createAsset(prj,"Vehicles/CustomCar.rrvehicle","VehicleAsset");

Input Arguments

project — Project folder for current session

Project object

Project folder for the current RoadRunner session, specified as a Project object.

Example: prj = rrApi.Project, where rrApi is the RoadRunner authoring API object, returns the Project object prj for the current RoadRunner session.

assetPath — Relative asset path

string scalar | character vector

Relative asset path, specified as a string scalar or character vector. createAsset accepts the file extensions .rrvehicle, .rrchar, and .rrbehavior for new assets. The specified extension must correspond to the type of asset specified by assetType:

• .rrvehicle extension — assetType must be "VehicleAsset".

• .rrchar extension — assetType must be "CharacterAsset".

• .rrbehavior extension — assetType must be "BehaviorAsset".

Note

By default, RoadRunner searches the Assets folder in your RoadRunner project when you specify a relative path to an asset. If you want to add an asset that is located outside the Assets folder in your RoadRunner project, use the <PROJECT> prefix to specify your current project folder before specifying the new path. For example, createAsset(prj,"<PROJECT>/CustomFiles/CustomVehicles/CustomSedan.rrvehicle","VehicleAsset").

assetType — Type of created asset

"VehicleAsset" | "CharacterAsset" | "BehaviorAsset"

Type of the created asset, specified as one of these options:

• "VehicleAsset" — Specifies the asset type of the created asset as Vehicle.

• "CharacterAsset" — Specifies the asset type of the created asset as Character.

• "BehaviorAsset" — Specifies the asset type of the created asset as Behavior. RoadRunner stores behavior asset data in .rrbehavior files.

Output Arguments

asset — Asset object

VehicleAsset object | CharacterAsset object | BehaviorAsset object

Asset object, returned as one of these objects:

• VehicleAsset — Represents an asset with the Vehicle asset type.

• CharacterAsset — Represents an asset with the Character asset type.

• BehaviorAsset — Represents an asset with the Behavior asset type. RoadRunner stores behavior asset data in .rrbehavior files.

Limitations

• The createAssets function does not support creating assets that use an externally referenced file, such as an .fbx file for a 3D model. If you have a custom file you want to use in your RoadRunner scenario, such as 3D model for a vehicle, add it to a folder in your RoadRunner project. For more information on creating custom assets for RoadRunner, see Create, Import, and Modify Assets (RoadRunner), Import Custom Vehicle Meshes (RoadRunner Scenario), and Import Custom Character Meshes (RoadRunner Scenario).

Version History

Introduced in R2025a