Vehicle Groups (*.vehGroup.json)

This page describes vehicle group files used by traffic, parking, missions, editor tools, and other gameplay systems.

A vehicle group is a named pool of vehicle model/config entries. It controls what may be spawned, but not where vehicles spawn or how they drive. Placement and behavior still come from traffic, parking, missions, sites, and navgraph data.

File Structure

Most authored vehicle groups use this shape:

{
  "type": "custom",
  "name": "Example Traffic Group",
  "tags": ["example", "traffic"],
  "data": [
    {
      "model": "covet",
      "config": "DXi_A"
    },
    {
      "model": "pickup",
      "config": "d15_4wd_A_facelift"
    }
  ]
}

Top-level fields

Vehicle entry fields

Some tools may preserve additional per-vehicle fields, such as paint or spawn-related metadata. Do not remove unknown fields from an existing group unless you know the consuming system does not need them.

Minimal one-car group:

{
  "type": "custom",
  "name": "One Car Test",
  "data": [
    {
      "model": "pickup",
      "config": "d15_4wd_A_facelift"
    }
  ]
}

File Locations

Shared vehicle groups can be stored under:

vehicleGroups/**/*.vehGroup.json

Level-specific groups can be stored in a level root:

levels/<levelName>/*.vehGroup.json

Common level-specific names:

levels/<levelName>/traffic.vehGroup.json
levels/<levelName>/police.vehGroup.json

Mission-specific groups are commonly stored with the mission:

gameplay/missions/<levelName>/<missionType>/<missionName>/custom.vehGroup.json

Lookup Behavior

Traffic and mission tools can load vehicle groups from different places depending on context:

When several matching files exist, tools may choose one from the matching set. Use clear file names and tags when a level or mission contains multiple groups.

Common Uses

Creating Groups With Tools

The easiest way to create a vehicle group is to use the in-game editor tooling:

1. Open the World Editor.
2. Open the Traffic Manager or the Vehicle Groups tool from the editor.
3. Select the vehicle models/configs you want in the group.
4. Save the group as a *.vehGroup.json file.
5. Place the file where the intended consumer will search for it.
6. Test the group with Traffic Manager, Mission Editor, or the gameplay feature that uses it.

Traffic Manager can also load a vehicle group file directly for testing. If the group loads there, but not in a mission or level, the problem is usually file location, naming, or the consuming setup rather than the file structure.

Writing Groups By Hand

Vehicle group files are simple enough to write manually:

1. Choose where the file should live.
2. Add type, name, and optional tags.
3. Add a data array.
4. Add one object per vehicle config.
5. Test the group in the system that consumes it.

When editing manually, verify model/config ids against known working vehicle configurations. A typo can make the group load but fail to spawn the intended vehicle.

Level Traffic Groups

For levels, the most common convention is:

traffic.vehGroup.json
police.vehGroup.json

Use traffic.vehGroup.json for ordinary ambient traffic and police.vehGroup.json for police spawning. These files should match the level’s region, era, and road network. For example, avoid using very large vehicles in a level with narrow roads unless that is part of the intended traffic mix.

To create a level group:

1. Build a temporary group in Traffic Manager or the Vehicle Groups tool.
2. Save it to the level root as traffic.vehGroup.json or police.vehGroup.json.
3. Load the level and spawn traffic.
4. Check variety, vehicle size, and performance.
5. Adjust the group until traffic feels appropriate for the level.

Mission Custom Groups

Missions can use a mission-local group when they need deterministic or restricted AI traffic. A common path is:

gameplay/missions/<levelName>/<missionType>/<missionName>/custom.vehGroup.json

Mission-local groups are useful when:

• Only specific vehicles should spawn for a challenge.
• A mission needs themed traffic independent of the level default.
• A test or tutorial must avoid random vehicle selection.

Keep mission custom groups small unless the mission intentionally needs variety.

To create a mission custom group:

1. Open the mission in Mission Editor.
2. Enable the custom vehicle group option for the relevant traffic/setup module.
3. Save or select custom.vehGroup.json in the mission folder.
4. Test the mission from a fresh start, not only from an editor preview.

Choosing Vehicles

Advanced authoring considerations:

• Prefer configs that are complete and spawn reliably.
• Consider vehicle size, weight, speed, and drivetrain for the target roads.
• For traffic groups, include enough variety to avoid repetition but not so much that rare vehicles dominate.
• For police groups, use configs with expected police equipment and behavior.
• Avoid configs that depend on mods unless the vehicle group is part of that mod and clearly requires them.
• If a config is renamed or removed, update every group that references it.

Troubleshooting

Group is not found

Check:

• The file is saved in a location searched by the consuming system.
• The file name matches the expected convention, such as traffic, police, or custom.
• The extension is exactly .vehGroup.json.
• The file is valid JSON.

Group loads but vehicles do not spawn

Check:

• Every model exists.
• Every config exists for the model.
• The consuming traffic or mission setup is actually using the group.
• The level has valid spawn roads, parking spots, or mission spawn data.

Wrong vehicles appear

Check:

• Another matching group file is being selected.
• A mission-specific group is overriding the level group.
• The gameplay system is using generated traffic instead of a custom group.

Validation Checklist

• The JSON file loads without errors.
• Every model exists.
• Every config exists for its model.
• The group file is saved where the consuming tool or system expects it.
• The group name and tags describe the intended use.
• The mission, level, or tool that expects the group can find it.
• The selected vehicles make sense for the roads, mission, and performance budget.

Related Pages

• Level Gameplay Data
• Traffic Signals
• Navigation Map