Skip to content

Item groups

Item groups associate items (e.g. coal, sand, TVs, etc.) with storage (vehicles, warehouses) without having to list all supported items in each storage. This makes mod compatibility easier and eliminates the need for compatibility patches.

Additionally, it standardizes the representation of similar items in the game, making it more predictable for players.

If your mod adds new items or storage assets (vehicles or warehouses), it's recommended to update them to utilize item groups.

Update item assets

  1. Set your item as belonging to one of available item groups using the new ItemGroupUri property.
  2. Set meshes used to display an item in different kind of storages using MeshUris property (keys are mesh tags).
1
2
3
4
5
6
7
{
    "ItemGroupUri": "base/bulk.itemgroup",
    "MeshUris": {
        "vehicle_heap": "base/gravel_item_heap.obj"
    },
    // ...
}

Update storage assets

Note

Different capacity, resolution, or spacing settings per item aren't supported by this approach. If it's essential for your mod, you should stick to using Items property.

By the way, you can mix both approaches.

.storages

  1. List desired item groups in the ItemGroupUris array.
  2. Set Items property to null.
{
-   "Items": {
-        "base/sand.item": null,
-        "base/gravel.item": null,
-   },
+   "Items": null,
+   "ItemGroupUris": [
+       "base/bulk.itemgroup"
+   ],
    // ...
}

.passengerstorages

  1. List desired item groups in the ItemGroupUris array.
  2. Move Capacity settings to the root.
  3. Set Items property to null.
{
-   "Items": {
-        "base/passenger.item": {
-           "Capacity": 30,
-            // ...
-       }
-   },
+   "Items": null,
+   "Capacity": 30,
+   "ItemGroupUris": [
+       "base/passenger.itemgroup"
+   ],
    // ...
}

.stackstorages

  1. List desired item groups in the ItemGroupUris array.
  2. Move essentinal Capacity, Resolution, and Spacing settings to the root (if set to null, they will be calculated automatically).
  3. Set MeshTag property to default.
  4. Set Items property to null.

.heapstorages

  1. List desired item groups in the ItemGroupUris array.
  2. Move essentinal Capacity, Resolution, and Spacing settings to the root (if set to null, they will be calculated automatically).
  3. Set MeshTag property to vehicle_heap.
  4. Set Items property to null.

Built-in groups

URI Items
base/bulk.itemgroup
base/general.itemgroup
base/long_general.itemgroup
base/mail.itemgroup
base/open_bulk.itemgroup
base/open_general.itemgroup
base/passenger.itemgroup

The next item groups are not used in the base game yet, but already can be utilized by mods.

URI
base/dangerous_liquid.itemgroup
base/expensive.itemgroup
base/liquid.itemgroup
base/perishable.itemgroup

Feedback wanted

You can share your suggestions for additional item categories to be included in the base game via Discord.

Mesh tags

Mesh tags are used to define what mesh should be used to display an item inside an open storage.

Base game provides the next mesh tags:

Mesh tag Storage Description
default .stackstorages Used to display items in stacks
vehicle_heap .heapstorages Used to display items as heap inside vehicles

Last update: July 26, 2023